Getting Started

The following steps will help you get wq-powered application up and running quickly.

I. Install wq

The easiest way to install wq is via the wq docker template, which includes a Dev Container as well as a production-ready Dockerfile for deployment to a cloud container service.

For more details, refer to any of the setup guides below:

Development Container

• GitHub Codespaces
• Docker Desktop

Production Container

• Azure App Service
• AWS App Runner

Direct Install

• SQLite on Ubuntu or Windows
• WSGI Webserver (Apache & PostgreSQL on Ubuntu)

If you are unsure which setup to start out with, try a Github Codespace since the setup process is fully automated.

II. Define your Data Model

To help get started, wq provides a simple survey schema with Observation and Category models. This can (and usually should) be replaced with a custom schema specific to your project needs. wq is extremely flexible to adapt to a variety of project workflows, but you may need to think a bit about how you want to structure your data before continuing. Once defined, the data schema will be used to automatically generate database tables as well as the forms for entering data.

See the following for more information on defining a data schema:

Data Model

Introduction to Django models and tips for creating them from an XLSForm definition.

Common Field Types

A comprehensive list of the common field / question types and conventions for using them in wq.

Nested Forms

Instructions for defining nested forms (“repeat groups” in XLSForm syntax) as well as user-definable attributes (e.g. EAV).

III. Customize your User Interface

Once your data model is defined and your REST API is running, wq will automatically generate fully functional “list”, “detail”, and “edit”/”new” views for managing the database. You can customize the UI by implementing custom views, input types, and/or other components.