Home > Guides > How To: Set up wq with SQLite

How To: Set up wq with SQLite

Note: We highly recomend leveraging the wq Dev Container via GitHub Codespaces or Docker Desktop. The instructions below do not leverage a container and require manual install steps that may interfere with other software on your machine.

The following steps should help you install wq and get a wq-powered web application running for local development and testing. These steps are tested on Ubuntu 20.04 LTS, but should work with minor changes on any OS that can run Python (Windows, OS X, etc.). On Windows, we recommend installing the Windows Subsystem for Linux (WSL) if possible.

  1. Install Python
  2. Create Project Directory
  3. Initialize wq Framework
  4. Initialize SQLite
  5. Start Django Server
  6. Optional: Enable GIS Support

Install Python

The first step in installing wq is to install Python. We recommend installing wq in a Python 3 venv virtual environment.

Ubuntu

On Ubuntu (including WSL), you may need to install the python3-venv package:

sudo apt update
sudo apt python3-venv

If you don’t already have it install SQLite as well

sudo apt install sqlite3

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.

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

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

The framework initialization step will take a few minutes when using npm, since it requires installing hundreds of npm packages instead of the prebuilt libraries included with the Python package. On the other hand, enabling npm makes it easier to integrate additional third-party JavaScript libraries and development tools as needed.

Windows

If using Windows (without WSL), install Python 3 from the Python website. The venv package is included with the Windows installation. If you plan to use wq’s Node.js & npm integration, you should also install Node.js.

Create Project Directory

Once Python is configured, you can create a new wq project using the following commands. The same commands will work in Bash (Ubuntu/WSL) as well as the CMD prompt (Windows).

mkdir myproject
cd myproject

python3 -m venv venv
. venv/bin/activate  # (on Windows: venv\Scripts\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 myproject .

# Answer prompts for:
#  - Web domain:    (Default is fine during development)
#  - Enable GIS?    (Leave default (N), or see below)
#  - Enable npm?    (Leave default unless you plan to use npm)

Initialize SQLite

Run the commands below to create the initial database tables and admin account.

cd db/
python manage.py migrate
python manage.py createsuperuser
cd ..

This should create a sqlite database in the conf/ directory.

Start Django Server

# generate htdocs folder via wq build
./deploy.sh 0.0.1  # (on Windows: deploy.bat 0.0.0)

# Start local Django server
cd db/
python manage.py runserver

Visit http://localhost:8000/ in a web browser to verify the new installation. 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 models.

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

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

Optional: Enable GIS Support

The instructions above make use of the --without-gis flag. If you would like to support geospatial input (e.g. map-drawn Polygons and Lines), you will need to enable GIS support via GeoDjango. To do this, you can specify wq create --with-gis or answer Y at the “Enable GIS?” prompt. You can also enable GIS for an existing project by uncommenting the lines referencing django.contrib.gis in each of the files under db/myprojects/settings/.

If you only need to support GPS coordinates, you can probably get by with numeric latitude and longitude fields and forgo the GeoDjango requirement.

Note that you will probably need to install the additional system libraries below to get GeoDjango to work.

Ubuntu

On Ubuntu, (including WSL), install the following libraries:

sudo apt install libsqlite3-mod-spatialite gdal-bin

In addition, ensure that the SPATIALITE_LIBRARY_PATH line in db/myproject/settings/dev.py is uncommented.

Windows

Installing GDAL and other GeoDjango requirements on Windows somewhat more involved. See the GeoDjango documentation for more information. Also, note that you will need to remove the .so extension from SPATIALITE_LIBRARY_PATH.