How To: Set up wq with SQLite
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.
- Install Python
- Create Project Directory
- Initialize wq Framework
- Initialize SQLite
- Start Django Server
- Optional: Enable GIS Support
Note: If you want to deploy wq on a public-facing webserver, you may want to set up wq with Apache & PostgreSQL instead of the process documented here.
The first step in installing wq is to install Python. We recommend installing wq in a Python 3 venv virtual environment.
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.
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 createin 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)
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.
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.
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