To install without Docker requires installing and configuring many services. See :ref:`step-by-step-install`.
Install Docker and Docker Compose. On Linux, you may need to create a docker group. On Mac, make sure you're in a directory that Virtual Box shares through to the VM (by default, anywhere in your home directory works).
For a production-ready Allura, follow the instructions in :file:`Allura/production-docker-example.ini`.
export COMPOSE_FILE=docker-compose-prod.yml and continue running the following commands.
This will give you HTTPS, settings for better performance and no debugging, and only expose necessary ports.
If you are running Docker inside a VM (or access it by a different hostname for any reason), edit
:file:`Allura/docker-dev.ini` and add these lines after
domain = hostname-or-ip base_url = http://hostname-or-ip:8080
Run the following commands in your allura directory:
Build/fetch all required images:
export COMPOSE_PROJECT_NAME=allura docker-compose build
Python and JS package setup (and first containers started):
docker-compose run web scripts/init-docker-dev.sh
Restart SOLR container, so it will see changes from the command above and create index:
docker-compose restart solr
Initialize database with test data:
docker-compose run taskd paster setup-app docker-dev.ini
If you want to skip test data creation you can instead run:
docker-compose run -e ALLURA_TEST_DATA=False taskd paster setup-app docker-dev.ini
Start containers in the background:
docker-compose up -d
You're up and running! Visit localhost:8080, or on a Mac or Windows whatever IP address Docker Toolbox is using. Then see our :ref:`post-setup-instructions` and read more below about the Docker environment for Allura.
Allura runs on the following docker containers:
These are created on first run.
Current directory mounted as :file:`/allura` inside containers. This means your current source code in your host environment is shared with the containers. You can edit Allura code directly, and the containers will reflect your changes.
Restarting all containers:
docker-compose up -d
View logs from all services:
docker-compose logs -f
You can specify one or more services to view logs only from them, e.g. to see outgoing mail:
docker-compose logs -f outmail
Update requirements and reinstall apps:
docker-compose run web pip install -r requirements.txt docker-compose run web ./rebuild-all.bash
You may want to restart at least "taskd" container after that in order for it to
pick up changes. Run
docker-compose restart taskd
Running all tests:
docker-compose run web ./run_tests
Running subset of tests:
docker-compose run web bash -c 'cd ForgeGit && nosetests forgegit.tests.functional.test_controllers:TestFork'
Connecting to mongo using a container:
docker-compose run mongo mongo --host mongo
You can log in with username admin1, test-user or root. They all have password "foo". (For more details on the default data, see :file:`bootstrap.py`)
There are a few default projects (like "test") and neighborhoods. Feel free to experiment with them. If you want to register a new project in your own forge, visit /p/add_project.
First of all you need to create a project, which will serve as a container for keeping site administrators (users who will have access to the :ref:`admin interface <site-admin-interface>`).
In order to do that:
By default all admins of "allura" project in "Projects" neighborhood are treated as site admins. If you want to use different project for that, change site_admins_project in :file:`development.ini`.
The :file:`development.ini` file is geared towards development, so you will want to review carefully and make changes for production use. See also :file:`production-docker-example.ini` which sets a variety of settings better for production (you will always need to customize some values like keys and domains).
Change [handler_console] section, so that logs go to a file and will include background tasks info.
class = allura.lib.utils.CustomWatchedFileHandler args = ('/path/to/allura.log', 'a')
Add write permissions to the :file:`/path/to/allura.log` for the user you use to run allura proccess.
beaker.session.secret = <your-secret-key> beaker.session.validate_key = <yet-another-secret-key>
The first one is used for simple cookies, the latter is used for encrypted cookies.
You can use the following command to generate a good key:
~$ python -c 'import os; l = 20; print "%.2x" * l % tuple(map(ord, os.urandom(l)))'
If you are running on a public facing server, you should check out some of the additional gunicorn configuration options at http://gunicorn.org/. For example, you'll want multiple worker processes to handle simultaneous requests, proxy behind nginx for added protection, etc.
If you'd like to use another webserver, here are a few options:
~$ pip install uwsgi # or install via system packages ~$ uwsgi --ini-paste-logged development.ini --virtualenv /PATH/TO/VIRTUALENV --http 0.0.0.0:8080
~$ pip install mod_wsgi # requires httpd2 devel libraries installed in the system ~$ mod_wsgi-express start-server development.ini --application-type paste --user allura --group allura --port 8080 --python-path /PATH/TO/VIRTUALENV/lib/python3.6/site-packages/
For any other wsgi server (e.g. mod_wsgi with Apache, or waitress) you will need a wsgi callable set up like this:
from paste.deploy import loadapp from paste.script.util.logging_config import fileConfig config_file = '/PATH/TO/Allura/development.ini' fileConfig(config_file) application = loadapp('config:%s' % config_file)
The :file:`development.ini` file has many options you can explore and configure.
To run SVN and Git services, see the :doc:`scm_host` page.
Some features may be added as separate Allura extensions
Allura can listen for email messages and update tools and artifacts. For example, every ticket has an email address, and emails sent to that address will be added as comments on the ticket. With Docker, this is already running on port 8825. If you are not running docker, run:
nohup paster smtp_server development.ini > /var/log/allura/smtp.log &
By default this uses port 8825. Depending on your mail routing, you may need to change that port number. And if the port is in use, this command will fail. You can check the log file for any errors. To change the port number, edit :file:`development.ini` and change :samp:`forgemail.port` to the appropriate port number for your environment.
You will need to customize your mail server to route mail for Allura to this service. For example with postfix you can use :samp:`transport_maps` with:
mydomain.com smtp:127.0.0.1:8825 .mydomain.com smtp:127.0.0.1:8825 *.mydomain.com smtp:127.0.0.1:8825
Various other settings may be necessary depending on your environment.
The following command can be used for quick and easy monitoring of outgoing email during development.
docker-compose logs -f outmail
python -u -m smtpd -n -c DebuggingServer localhost:8826
This will create a new debugging server that discards messages and prints them to stdout.
Allura has a pluggable authentication system, and can use an existing LDAP system. In your config file (e.g. :file:`development.ini`), there are several "ldap" settings to set:
Restart Allura and you should be all set. Now users can log in with their LDAP credentials and their Allura records will be automatically created the first time they log in.