For a simpler setup using Docker images, see :ref:`docker-install` instead.
In these instructions, we'll use VirtualBox and Ubuntu 22.04 to create a disposable sandbox for Allura development/testing. Allura should work on other Linux systems (including OSX), but setting up all the dependencies will be different.
Alt-F1
to switch to the first console.Before we begin, you'll need to install some system packages. Allura currently supports Python 3.8 through 3.11. The steps below use Python 3.11.
~$ sudo apt-get update ~$ sudo apt-get install gpg gpg-agent ~$ sudo apt-get install software-properties-common ~$ sudo add-apt-repository ppa:deadsnakes/ppa ~$ sudo apt-get update ~$ sudo apt-get install git-core python3.11 python3.11-dev gcc libmagic1 libssl-dev libldap2-dev libsasl2-dev libjpeg8-dev zlib1g-dev libffi-dev
To install MongoDB, follow the instructions here.
Optional, for SVN support:
~$ sudo apt-get install subversion libsvn-dev make g++ python3-svn
The first step to installing the Allura platform is installing a virtual environment via venv
. This helps keep our distribution python installation clean.
~$ sudo apt-get install python3.11-venv
Then create a virtual environment. We'll call our Allura environment 'env-allura'.
~$ python3.11 -m venv env-allura
This gives us a nice, clean environment into which we can install all the allura dependencies. In order to use the virtual environment, you'll need to activate it:
~$ source env-allura/bin/activate
You'll need to do this whenever you're working on the Allura codebase so you may want to consider adding it to your :file:`~/.bashrc` file.
(env-allura)~$ sudo mkdir -p /var/log/allura (env-allura)~$ sudo chown $(whoami) /var/log/allura
Now we can get down to actually getting the Allura code and dependencies downloaded and ready to go. If you don't have the source code yet, run:
(env-allura)~$ mkdir src (env-allura)~$ cd src (env-allura)~/src$ git clone https://gitbox.apache.org/repos/asf/allura.git/
If you already reading this file from an Allura release or checkout, you're ready to continue.
We'll upgrade pip to make sure its a current version, and then install all Allura python dependencies with it.
(env-allura)~/src$ cd allura (env-allura)~/src/allura$ pip install -U pip (env-allura)~/src/allura$ pip install -r requirements.txt
This may take a little while.
Optional, for SVN support: install the wheel package then use the pysvn-installer script to build a pysvn wheel.
(env-allura)~/src/allura$ pip install wheel (env-allura)~/src/allura$ curl https://raw.githubusercontent.com/reviewboard/pysvn-installer/master/install.py | python
Next, run this to set up all the Allura tools:
(env-allura)~/src/allura$ ./rebuild-all.bash
Note
If you only want to use a few tools, run this instead:
(env-allura)~/src/allura$ cd Allura (env-allura)~/src/allura/Allura$ python setup.py develop (env-allura)~/src/allura/Allura$ cd ../ForgeWiki # required tool (env-allura)~/src/allura/ForgeWiki$ python setup.py develop # repeat for any other tools you want to use
The Allura forge consists of several components, all of which need to be running to have full functionality.
We have a custom config ready for use.
(env-allura)~$ cd /tmp (env-allura)/tmp$ sudo apt-get install openjdk-8-jre-headless unzip (env-allura)/tmp$ wget -nv https://archive.apache.org/dist/lucene/solr/5.3.1/solr-5.3.1.tgz (env-allura)/tmp$ tar xvf solr-5.3.1.tgz solr-5.3.1/bin/install_solr_service.sh --strip-components=2 (env-allura)/tmp$ sudo ./install_solr_service.sh solr-5.3.1.tgz (env-allura)/tmp$ cd ~/src/allura (env-allura)~/src/allura$ sudo -H -u solr bash -c 'cp -R solr_config/allura/ /var/solr/data/' (env-allura)~/src/allura$ sudo service solr start
The default configuration stores repos in :file:`/srv`, so we need to create those directories:
~$ sudo mkdir /srv/{git,svn,hg} ~$ sudo chown $USER /srv/{git,svn,hg} ~$ sudo chmod 775 /srv/{git,svn,hg}
If you don't have sudo
permission or just want to store them somewhere else, change the :file:`/srv` paths in :file:`development.ini`
If you want to set up remote access to the repositories, see :ref:`scm_hosting`
Allura uses a background task service called "taskd" to do async tasks like sending emails, and indexing data into solr, etc. Let's get it running
(env-allura)~$ cd ~/src/allura/Allura (env-allura)~/src/allura/Allura$ nohup paster taskd development.ini > /var/log/allura/taskd.log 2>&1 &
If you're using a released version of Allura, these are already done for you.
Otherwise, install nodejs via the Ubuntu instructions or other instructions. Then run:
(env-allura)~$ cd ~/src/allura (env-allura)~$ npm ci (env-allura)~$ npm run build
In order to initialize the Allura database, you'll need to run the following:
For development setup:
(env-allura)~/src/allura/Allura$ paster setup-app development.ini
For production setup:
(env-allura)~/src/allura/Allura$ ALLURA_TEST_DATA=False paster setup-app development.ini
This shouldn't take too long, but it will start the taskd server doing tons of stuff in the background. Once this is done, you can start the application server:
(env-allura)~/src/allura/Allura$ gunicorn --reload --paste development.ini -b :8080 # add --daemon to run in the background
Go to the Allura webapp running on your local machine port 8080.
$ ALLURA_VALIDATION=none ./run_tests