Quick Start

This guide provides a quick start for developers to set up the Citizen Voice application on their local machines. It covers the essential steps to get the application running, and start developing.

Prerequisites

For Django APIs

  • Python: Ensure you have Python 3.10 or higher installed on your machine. You can download it from Python’s official website. Required if developing the APIs.

  • PostgreSQL: Ensure you have PostgreSQL 16.0 or higher installed and running with the PostGIS extension. You can download it from PostgreSQL’s official website. Required if developing the APIs.

  • GDAL: Install a version of GDAL compatible with your version of GeoDJango. Installing GDAL can be combersome in some operatint systems. In such cases, using a conda environment might be the quickest way to start.

For Citizen Mappping and Community Dashboard

  • Node.js: Ensure you have Node.js (version 22 or higher) installed. You can download it from Node.js official website.

  • Yarn: We prefer yarn but you can use another dependencies manager compatible with NuxtJS 3.

For Services Deployment and Configuration

  • Docker: Ensure you have Docker and Docker Compose installed on your machine (v2.22.0 or later). You can download it from Docker’s official website.

Setting Up the Development Environment

  1. Clone the repository, the latest version is in the devel branch.

Django APIs

  1. Add an .env file to the root of the repository with the following variables.

POSTGRES_USER=citizen
POSTGRES_DBASE=civo
POSTGRES_PWD=admin@voice
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
DJANGO_DB_ENGINE=postgis
DJANGO_ALLOWED_HOSTS= localhost 127.0.0.1 [::1] api cvportal
DJANGO_DEBUG=1 # 0 for production

  1. Create a directory in the root of the repository called secrets/, and create the secrets for the Django token and the database password as follows:

# file name: django_token.txt
<django-token-plain-text>

# file name: postgres_password.txt
# Make sure this matches the one used in POSTGRES_PWD
<postgres-superuser-password>

  1. Create a new superuser on your PostgreSQL with a name and password that matches the ones used in the .env file and the postgres_password.txt secret.

  2. Create a PostgreSQL database in your server with a name that matches POSTGRES_DBASE above, and make the new user an owner of the database, and allow all previlages for this user to the database.

  3. Install the Django depencies in citizenvoice/requirements.txt

pip install -r citizenvoice/requirements.txt

  1. Make and apply the migrations. Do the following:

cd citizenvoice/
python manage.py makemigrations
python manage.py migrate

# If you get an error, 
## check your database configuration, .env, and settings.py 
# If you see this: No settings is available for selected database engine!
## Make sure the lines 34 and 36 in settings.py ARE NOT commented. ## And that the names in your .env file matches the ones used by your database.

  1. Start the Django development server.

python manage.py runserver

# server will start on http://127.0.0.1:8000/

The APIs will be available as follows:

  • Voice: http://localhost:8000/voice/v3

  • Civilian: http://localhost:8000/civilian/v1

  • Django Admin: http://localhost:8000/api/admin

Important

Notice that when running the Apps idependently, the TCP port is part of the URLs

  1. Create a superuser for the Django Admin App

python manage.py createsuperuser

# enter a username and password. 
# Use this credentials to login to the Django Admin

Citizen Mapping

This is a NuxtJS 3 app.

  1. Install the dependencies.

cd maptool/
yarn install

  1. Rund the App.

yarn run dev

# Press CTRL + C to stop the app

Community Dashboard

This is a NuxtJS 3 app.

  1. Install the dependencies.

cd cv-portal/
yarn install

  1. Rund the App.

yarn run dev

# Press CTRL + C to stop the app

Important

At this point, the Apps contained in the repository can be developed and test. However, the database remains empty (except for user information). The /citizenvoice/civilian-db.json contains sample data (surveys and answers) that can be loaded in an empty database using the Django command:

python manage.py loaddata civilian-db.json

Services Deployment

We use Docker to create and manage containers for integrating the Apps and services.

There are docker files for the following Apps:

  • Django APIs

  • Citizen Mapping

  • Community Dashboard

We use Docker compose to integrate the services and NginX as reverse proxy.

Warning

When building the containers, lines 34 and 36 in settings.py must be commented out. Otherwise the environment variables loaded by Django and Docker compose might conflict and some services won’t work as expected.

  1. Build the containers

# from CitizenVoice/
docker compose build

  1. Run the containers

docker compose --env-file .env up

The following services will be available:

  • Voice API: http://localhost/voice/v3

  • Civilian API: http://localhost/civilian/v1

  • Django Admin: http://localhost/api/admin

  • Mapping Citizen App: http://localhost/citizen-map

  • Community Dashboard: http://localhost/api/cv-portal

Important

Notice that when using Docker, the TCP port is not part of the URLs