Installation

To install without Docker requires installing and configuring many services. See Step-by-Step Installation.

Using Docker

First run

Download the latest release of Allura, or clone from git for the bleeding edge.

Install Docker. On Linux, you may need to create a docker group.

Note

For a production-ready Allura, follow the instructions in Allura/production-docker-example.ini. Then run 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.

Note

If you are running Docker inside a VM (or access it by a different hostname for any reason), edit Allura/docker-dev.ini and add these lines after [app:main]

domain = hostname-or-ip
base_url = http://hostname-or-ip:8080

Replace hostname-or-ip with the actual hostname or external IP address. If you change this setting later, just run docker compose restart web

Run the following commands in your allura directory:

Build/fetch all required images:

docker compose build

Note

You can override the python version by adding --build-arg PY_VERSION=3.11 for example.

Python and JS package setup (and first containers started):

docker compose run --rm 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 --rm taskd paster setup-app docker-dev.ini

Note

If you want to skip test data creation you can instead run: docker compose run --rm -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 whatever IP address you’re running Docker on). Then see our Post-setup instructions and read more below about the Docker environment for Allura.

Note

Older versions of Docker compose might not recognize image names that contain hyphens throwing the following error Error response from daemon: pull access denied for allura-web, repository does not exist or may require 'docker login': denied: requested access to the resource is denied

You will need to either upgrade to the lastest version of Docker compose or edit and replace the images names hyphens with underscores in docker-compose.yml and docker-compose-prod.yml.

Containers

Allura runs on the following docker containers:

  • web

  • mongo

  • taskd

  • solr

  • inmail

  • outmail

Host-mounted volumes

These are created on first run.

Current directory mounted as /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.

Python environment:

  • ./allura-data/virtualenv/bin/python

Services data:

  • ./allura-data/mongo - mongo data

  • ./allura-data/solr - SOLR index

  • ./allura-data/scm/{git,hg,svn} - code repositories

  • ./allura-data/scm/snapshots - generated code snapshots

Note

The ./allura-data/ path can be overriden by setting the LOCAL_SHARED_DATA_ROOT environment variable

Ports, exposed to host system

Useful commands

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 --rm web pip install -r requirements.txt
docker compose run --rm 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

Run all tests:

docker compose run --rm web ./run_tests

Running subset of tests:

docker compose run --rm web bash -c 'cd ForgeGit && pytest forgegit/tests/functional/test_controllers.py::TestFork'

Connecting to mongo using a container:

docker compose run --rm mongo mongo --host mongo

Post-setup instructions

Logging in and sample projects

You can log in with username admin1, test-user or root. They all have password “foo”. (For more details on the default data, see 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.

Create project for site-admin

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 admin interface).

In order to do that:

  • open main page of the site in your browser

  • go to “Projects” neighborhood (What are neighborhoods?)

  • click “Register a new project” link

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 development.ini.

Change default configuration

The development.ini file is geared towards development, so you will want to review carefully and make changes for production use. See also 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 /path/to/allura.log for the user you use to run allura proccess.

Change the secret key used for signing session cookies.

beaker.session.jwt_secret_keys = <secret-key>

You can use the following command to generate a good key:

~$ python -c 'import secrets; print(secrets.token_hex());'

Production-quality web server

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:

uWSGI

~$ pip install uwsgi  # or install via system packages
~$ uwsgi --ini-paste-logged development.ini --virtualenv /PATH/TO/VIRTUALENV --http 0.0.0.0:8080

mod_wsgi-express

~$ 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.11/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)

Configuring Optional Features

The development.ini file has many options you can explore and configure.

To run SVN and Git services, see the SCM Host Setup page.

Some features may be added as separate Allura extensions

Enabling inbound email

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 development.ini and change 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 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.

SMTP in development

The following command can be used for quick and easy monitoring of outgoing email during development.

docker compose logs -f outmail

If you are running locally without docker, run this command. Be sure the port matches the smtp_port from your development.ini (8826 by default).

python -u -m smtpd -n -c DebuggingServer localhost:8826

This will create a new debugging server that discards messages and prints them to stdout.

Using LDAP

Allura has a pluggable authentication system, and can use an existing LDAP system. In your config file (e.g. development.ini), there are several “ldap” settings to set:

  • Change auth.method to: auth.method = ldap

  • Set all the auth.ldap.* settings to match your LDAP server configuration. (auth.ldap.schroot_name won’t be used, don’t worry about it.)

  • Keep auth.ldap.autoregister = true This means Allura will use existing users from your LDAP server.

  • Set auth.allow_user_registration = false since your users already are present in LDAP.

  • Change user_prefs_storage.method to user_prefs_storage.method = ldap

  • Change user_prefs_storage.ldap.fields.display_name if needed (e.g. if display names are stored in a different LDAP attribute).

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.

Note: if you want users to register new accounts into your LDAP system via Allura, you should turn off autoregister and turn on allow_user_registration