Navigate to the folder you have downloaded Foreman to. After installation, follow these steps.

1. Config File

In the foreman\config folder there is a config_template.ini file. Copy this file and rename to config.ini. You will need to add your database options here.

1.1 Using SQLite [Default]

If using SQLite, leave the entries blank apart from database_type and database_name. This is the config default.

username =
password =
database_name = foreman.db
port_number =
database_type = sqlite
database_location =

1.2 Using Postgres

Create a new database in Postgres (I recommend using the name 'foreman'). Fill in the username and password used to connect to your postgres instance. Change the default port and database location if required.

username =
password =
database_name = foreman
port_number = 5432
database_type = postgres
database_location = localhost

1.3 Other config options

• debug: setting this to true will mean an interactive debugger kicks in instead of a 500 server error page. Useful if you are playing about, dangerous if on a live system!
• send_email: set to true if you want Foreman to send emails. Vital if this is a live system - users will get initial passwords and confirmation emails this way.
• from_address: the email address you would like emails to appear to be sent from.
• email_host: the email host, usually localhost if you are dealing with email yourself.
• admin_email = the email address for the first account which is automatically created. This is the administrator account and is used to administer the website and add other users.
• website_domain = the domain that foreman is hosted on, e.g. http://your-foreman-instance.com.

2. Running Foreman

2.1 Running Foreman on a standalone machine

To run Foreman, use the following command. This will initialise the database and add in the default data. Note: Remember to remove the < and > around the config path's.

python run_foreman.py setup <path to config file>

Foreman also comes with a basic example database with 50 randomly created cases with varying amounts of tasks and evidence. To set the example database up, run:

python run_foreman.py setup_example <path to config file>

To run foreman, use the following command:

python run_foreman.py runserver <path to config file>

This will now run Foreman. Go to your favourite web browser (Google Chrome or Firefox is recommended) and go to http://localhost:5000. You can change the port and a few other settings by typing -h or --help to get the full options.

2.2 Running Foreman using Apache or other webserver

You will have to configure your webserver to run Foreman. The HOWTO Python Guide may be of help. Foreman does not come with a .WSGI file.

2.3 Troubleshooting

If you run the setup_example version and get an error in the command line which is similar to this:

IOError: [Errno 2] No such file or directory: 'C:\Python27\Lib\site-packages\Foreman_Forensics-0.0.1-py2.7.egg\foreman\utils\test_case_names.txt'**

This means that you are running Foreman from the Python installation files rather than the downloaded folder. In the installation, Python copies across all Python files, but not text files, images and other important files. Therefore, after installation, you should move your downloaded Foreman folder to where you'd like to keep it (Program Files or a root directory perhaps) and run Foreman from within this folder. This will have all the files you need and will not cause the error above.

3. First Use

A default administrator account was created when the setup script was run. When Foreman is running, you will need to log in as the administrator to set up cases, tasks and approve other user registrations. The login details are:

• username: administrator
• password: changeme

Please change the password after you have logged in.

If you are using the setup_example version - all other usernames have the password set to password.

4. Next Steps

User documentation is being written up on the blog.