Home > Guides > How To: Set up wq with Apache & PostgreSQL

How To: Set up wq with Apache & PostgreSQL

Note: We highly recomend deploying to a hosted container service like Azure App Service or AWS App Runner. The instructions below do not leverage a container and require manual install steps that may interfere with other software on your server.

To run wq on a public website, you will need a WSGI-capable webserver like Apache, and a database to host the application. You will also need to obtain or configure a DNS record pointing a domain or subdomain to your server. wq.db is generally used with PostgreSQL and PostGIS, but any Django-supported database will work. These instructions assume you will be using Apache and PostGIS. These steps are tested on Ubuntu 20.04 LTS.

  1. Install System Libraries
  2. Create Project Directory
  3. Initialize wq Framework
  4. Configure PostgreSQL
  5. Configure Apache

Note: If you are only experimenting with wq on your local machine, you may want to set up wq with SQLite instead of the more complex process documented here.

Install System Libraries

On Ubuntu 20.04, the default PostgreSQL version is 12 and the PostGIS version is 3. On a different Ubuntu version, you may need to find the corresponding PostGIS package. The names of the other libraries will generally be the same.

sudo apt update
sudo apt install apache2 libapache2-mod-wsgi-py3 postgresql-12-postgis-3 python3-venv

Optional: Install Node

If you plan on using wq’s optional npm integration, you will also need to install node and npm. If you do so, we recommend installing from NodeSource. You can also install npm from Ubuntu universe, but (as of this writing) that requires 563MB of dependencies including the deprecated Python 2.

Note: wq currently supports Node 14 and npm 6. Support for Node 16 and npm 7 / 8 will be added in a future release.

curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt install nodejs

Create Project Directory

We recommend installing wq in a venv virtual environment. This isolates the project dependencies and makes it easier to run multiple wq-powered applications on the same server.

export PROJECTNAME=myproject

cd /var/www/
sudo mkdir $PROJECTNAME
sudo chown `whoami` $PROJECTNAME
cd $PROJECTNAME
python3 -m venv venv
. venv/bin/activate
python -m pip install --upgrade pip
python -m pip install wheel

Initialize wq Framework

Note that the command name changed from wq start to wq create in wq 1.3.

python -m pip install wq

# Note the trailing dot since we are already in the project folder
wq create $PROJECTNAME .

# Answer prompts for:
#  - Web domain:    (Change to match DNS)
#  - Enable GIS?    (Default is N, change to Y)
#  - Enable npm?    (Leave default as N unless you plan to use npm)

sudo chown www-data media/ # give Apache user permission to save uploads

Configure PostgreSQL

# (edit /etc/postgresql/12/main/pg_hba.conf and/or pg_ident.conf to set permissions)
sudo systemctl reload postgresql
createuser -Upostgres $PROJECTNAME
createdb -Upostgres -O$PROJECTNAME $PROJECTNAME
psql -Upostgres $PROJECTNAME -c "CREATE EXTENSION postgis;"

# (edit db/$PROJECTNAME/settings/prod.py with database info, if different than above)

# Make sure manage.py points to PostgreSQL, not SQLite
rm db/$PROJECTNAME/settings/dev.py
# (edit manage.py and replace '.dev' with '.prod')

# Install database tables & create admin account
cd db/
./manage.py migrate
./manage.py createsuperuser

Configure Apache

# (edit conf/$PROJECTNAME.conf and verify settings)
sudo ln -s /var/www/$PROJECTNAME/conf/$PROJECTNAME.conf /etc/apache2/sites-available/
sudo a2ensite $PROJECTNAME
# optional: disable existing default site and make $PROJECTNAME the server default
# sudo a2dissite 000-default
sudo systemctl apache2 restart

# generate htdocs folder via wq build
./deploy.sh 0.0.1

# To Enable HTTPS:
# (edit conf/$PROJECTNAME.conf, comment out WSGIDaemonProcess line)
# (see https://github.com/certbot/certbot/issues/1820)
sudo apt install certbot
sudo a2enmod ssl
sudo certbot --apache
# (edit /etc/apache2/sites-enabled/$PROJECTNAME-le-ssl.conf, uncomment WSGIDaemonProcess line)

Visit the site in a web browser to verify the new installation. You’ll probably need to type in the server’s IP address instead of the project name until your DNS is configured. When the application loads, you should see the default wq-themed app template with links to log in and out, as well as to manage the default Category and Observation tables.

Hint: Try logging in, then creating a Category, then creating an Observation.

You are now ready to start describing your data model to create additional survey types, which will appear on the home screen after you rebuild the application with deploy.sh.