Database setup

View On GitHub

WebApollo uses a database backed authentication by default that uses PostgreSQL. Make sure to understand the postgres configuration for configuring the database and see our troubleshooting guide to help with any problems with these steps.

User database

Web Apollo uses a database to determine who can access and edit annotations for a given sequence.

First we'll need to create a database to store our authentication data. You can call this database whatever you want, but remember the name of it as you'll need to point the configuration to it. For the purposes of this guide, we'll call it web_apollo_users.

Also, you might want to create a new postgres user account to manage the database. We'll have the user web_apollo_users_admin with password web_apollo_users_admin who has database creation privilege. This is not essential, but it makes it easier to administer because it doesn't tie the Web Apollo database to a specific operating system user.

Depending on how your database server is setup, you might not need to set a password for the user. See the PostgreSQL documentation for more information. We'll assume that the database is in the same server where Web Apollo is being installed ("localhost"). These commands should be run as the postgres user.

Create new postgres user (optional)

$ sudo su postgres
$ createuser -P web_apollo_users_admin
Enter password for new role: 
Enter it again: 
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n

Create new authentication database

Now we can create a new database that is owned by the web_apollo_users_admin user. We will use the "-h localhost" flag to force host based authentication instead of peer authentication.

$ createdb -U web_apollo_users_admin web_apollo_users -h localhost

Now that the database is created, we need to load the schema to it.

psql -U web_apollo_users_admin web_apollo_users -h localhost < tools/user/user_database_postgresql.sql

Now the user database has been setup, and you can run accessory scripts to add users and tracks.

Create a Web Apollo login

Next we'll use the script in WEB_APOLLO_DIR/tools/user to create a user with access to Web Apollo. Let's create a user in the Web Apollo database named web_apollo_admin with the password web_apollo_admin.

tools/user/ -D web_apollo_users -U web_apollo_users_admin -P web_apollo_users_admin -u web_apollo_admin -p web_apollo_admin

Note that the default mode add_user is to produce encrypted passwords using the EncryptedLocalDbUserAuthentication with the PBKDF2 algorithm. Other options for authentication include:

  • EncryptedLocalDbUserAuthentication (Default as of 1.0.4)
  • LocalDbUserAuthentication
  • DrupalDbUserAuthentication (For Mozilla Persona)
  • RemoteUserAuthentication (For LDAP)
  • OauthUserAuthentication (For Oauth providers)

Use the authentication_class tag in config.xml to configure this option.

Initialize permissions for Web Apollo login

Next we'll add the annotation tracks ids for the genomic sequences for our organism. We'll use the script to add the chromosome or sequence IDs to our database. But first we need to generate a file of the genomic sequence ids for the script. For convenience, there's a script called in the same directory which will go through a FASTA file and extract all the ids from the deflines. Let's first create the list of genomic sequence ids. We'll store it in ~/scratch/seqids.txt. We'll want to add the prefix "Annotations-" to each identifier.

mkdir ~/scratch
tools/user/ -p Annotations- -i WEB_APOLLO_SAMPLE_DIR/scf1117875582023.fa -o ~/scratch/seqids.txt

Now we'll add those ids to the user database.

tools/user/ -D web_apollo_users -U web_apollo_users_admin -P web_apollo_users_admin -t ~/scratch/seqids.txt

Now that we have an user created and the annotation track ids loaded, we'll need to give the user permissions to access the sequence. We'll have the all permissions (read, write, publish, user manager). We'll use the script in the same directory. We'll need to provide the script a list of genomic sequence ids, like in the previous step.

tools/user/ -D web_apollo_users -U web_apollo_users_admin -P web_apollo_users_admin -u web_apollo_admin -t ~/scratch/seqids.txt -a


We're all done setting up the user database. You can now add your postgres user and password login to Follow the build guide for more details

Note that we're only using a subset of the options for all the scripts mentioned above. You can get more detailed information on any given script (and other available options) using the "-h" or "--help" flag when running the script.