Skip to content

Running the Wagtail based CAP Composer in a standalone Wagtail site

License

Notifications You must be signed in to change notification settings

wmo-raf/cap-composer-web

Repository files navigation

CAP Composer Web

Running the Wagtail based CAP Composer in a standalone Wagtail site.

This repository contains a sample Docker Compose setup and configuration to include and run the CAP Composer in a separate standalone Wagtail site, without necessarily including the entire ClimWeb components.

The CAP Composer is a Wagtail based Django package/app that provides NMHSs a user-friendly interface for creating and managing CAP alerts.

Prerequisites

Before following the steps below, make sure you have the following set up:

  • Docker Engine & Docker Compose Plugin : Ensure that Docker Engine is installed and running on the machine where you plan to execute the docker-compose command https://docs.docker.com/engine/install/. Docker Engine is the runtime environment for containers.

Installation


Warning for Windows users: To avoid any installation issues, ensure that your default line endings are set to LF in your IDE.

For example, in VS Code you should ensure that the bottom right says 'LF' and not 'CRLF'. If you continue to run into problems, you may consider modifying how Git handles line ending conversion as well (see the core.autocrlf section of this page for more information).


1. Clone the Repository

git clone https://github.com/wmo-raf/cap-composer-web.git

2. Setup environmental variables

Copy the .env.sample file to a .env file

cp .env.sample .env

Edit and replace variables appropriately using your text editor. Here is an example using nano text editor.

nano .env

See environmental variables' section below for more details on the required variables

3. Create Wagtail static and media directories on the host machine and set correct permissions

Ensure you are using the correct paths as set in the .env file for the CAP_STATIC_VOLUME and CAP_MEDIA_VOLUME variables.

mkdir -p ./docker/capsite/static
mkdir -p ./docker/capsite/media

Update the permissions for the directories

Note: This step is not necessary on Windows machines.

sudo chown <CAP_GID>:<CAP_UID> ./docker/capsite/static
sudo chown <CAP_GID>:<CAP_UID> ./docker/capsite/media

Replace <CAP_GID> and <CAP_UID> with the values set in the .env file for the CAP_GID and CAP_UID variables

4. Build and Run the Docker Containers

docker-compose build
docker-compose up

To run the containers in the background, use the -d flag

docker-compose up -d

5. Create Superuser

docker-compose exec cap_web python manage.py createsuperuser

Environmental Variables

Variable Name Description Required Default Value Details
CAP_UID The id of the cap user Yes 1000
CAP GID The id of the cap group Yes 1000
CAP_DB_USER Postgres Database user Yes
CAP_DB_NAME Postgres Database name Yes
CAP_DB_PASSWORD Postgres Database password Yes Avoid using the '@' and '$' or any other special characters without escaping them. If you have to include them, first make sure your password is URL-Encoded to avoid errors
CAP_DB_VOLUME Docker Database volume path Yes ./docker/dbdata
CAP_FERNET_KEY The key used for encryption of MQTT passwords Yes 44 character URL-safe string, e.g. ERKBpLzB_P8azusL-CGK-LGZkV8T8edmmN4oYLi0w3Q=
CAP_DEBUG Django Debug mode No False
CAP_SITE_NAME Wagtail Site name No CAP Composer
CAP_ADMIN_URL_PATH Admin URL path No cap-admin
CAP_TIME_ZONE A string representing the time zone for this installation.See the list of time zones. Set this to your country timezone. No UTC List of tz database time zones
CAP_SECRET_KEY A secret key for a particular Django installation. This is used to provide cryptographic signing, and should be set to a unique, unpredictable value. Django will refuse to start if SECRET_KEY is not set Yes Avoid the $ here as well. You can use this online tool https://djecrety.ir to generate the key and paste. Make sure it does not include the $ character
CAP_ALLOWED_HOSTS A list of strings representing the host/domain names that this Django site can serve. This is a security measure to prevent HTTP Host header attacks, which are possible even under many seemingly-safe web server No * Django Allowed Hosts.
CAP_SMTP_EMAIL_HOST Django SMTP email host. Read more about sending Emails on Django here No
CAP_SMTP_EMAIL_PORT Django SMTP email port No
CAP_SMTP_EMAIL_USE_TLS Django SMTP email use TLS No True
CAP_SMTP_EMAIL_HOST_USER Django SMTP email host user No
CAP_SMTP_EMAIL_HOST_PASSWORD Django SMTP email host password No
CAP_ADMINS Django Admin emails No
CAP_DEFAULT_FROM_EMAIL Django Default from email No
CAP_STATIC_VOLUME Docker Static volume path Yes ./docker/capsite/static
CAP_MEDIA_VOLUME Docker Media volume path Yes ./docker/capsite/media
CAP_TLS_VOLUME Docker CAP TLS volume path No ./docker/capsite/tls
CAP_CERT_PATH CAP XML Signing Certificate path No
CAP_PRIVATE_KEY_PATH CAP XML Signing Private key path No
CAP_SIGNATURE_METHOD CAP XML Signature method No RSA_SHA256
CAP_GUNICORN_NUM_OF_WORKERS Number of Gunicorn workers No 4
CAP_GUNICORN_TIMEOUT Gunicorn timeout No 300
CAP_NGINX_PORT Docker Nginx port Yes 80
CAP_BROKER_USERNAME MQTT Broker username Yes cap
CAP_BROKER_PASSWORD MQTT Broker password Yes
CAP_BROKER_QUEUE_MAX MQTT Broker queue max Yes 1000

Admin Interface

1. Access the Wagtail Admin

The admin interface can be accessed at http://<ip_or_domain>:<CAP_NGINX_PORT>/<CAP_ADMIN_URL_PATH>. Replace <ip_or_domain> with the IP address or domain name of the site and <CAP_NGINX_PORT> with the port number where the site is running and <CAP_ADMIN_URL_PATH> with the admin URL path as set in the environmental variables.

For example, if the site is running on http://127.0.0.1:8000 and the admin URL path is set to cap-admin, the admin interface can be accessed at http://127.0.0.1:8000/cap-admin.

Below is how the admin interface will look when first accessed.

Wagtail Admin

Login with the superuser credentials created in step 5 above.

2. Update Wagtail Site Settings

Navigate to Settings > Sites to update the site settings.

Wagtail Site Settings

Click on the default site (localhost) to edit:

Wagtail Site Settings

Hostname: Should be the IP name or domain name of the site, without the protocol (http:// or https://).

Port: The port number where the site is running. For http, it is usually 80 and for https, it is usually 443.

Site Name: The name of the site.

3. Update CAP Base Settings

Before creating a CAP alert page, you will need to update the CAP Base settings. Navigate to CAP Alerts > CAP Base Settings

CAP Base Settings

Update CAP Sender Details

This section contains the details of the CAP sender. The details are used to populate the sender and contact element in the CAP alert message.

CAP Sender Details

For the WMO Register of Alerting Authorities OID, you go to the WMO Register of Alerting Authorities site and select your country, then copy the OID numbers as indicated in the example image below for Kenya Meteorological Service¬.

WMO Register of Alerting Authorities

Update Hazard Event Types

This section contains the list of hazard event types that can be used in the CAP alert message. This list should only include events monitored by the sending authority. You can select from a list of WMO defined event types or add a new custom one, as monitored by the sending authority. You can select an icon to represent the event type.

Hazard Event Types

Update Audience Types

This section contains the different audience types that can be used in the CAP alert message. You can create as many audience types as needed. Usually, you might only need to create one audience type like General Public for public alerts.

Audience Types

Create Predefined Areas

This section contains the predefined areas that can be used in the CAP alert message. The CAP tool allows to create alert areas using different tools including:

  • Drawing a polygon on the map
  • Drawing a circle on the map
  • Selecting an area from pre-loaded Administrative Boundaries
  • Selecting an area from a list of predefined areas

NOTE: You can find more details on the functionalities and capabilities of the editor in the CAP Composer package repository itself.

For an area to be selected from predefined areas, it needs to be created here first and saved. You can use the drawing tools here to trace the predefined areas.

Predefined Areas

4. Create a CAP Alert

Navigate to CAP Alerts > Alerts to create a new CAP alert. Click on Add cap alert page to create a new alert. This will open a form where you can fill in the details of the alert.

Create CAP Alert

5. Importing CAP Alerts from external sources

The CAP Composer tool allows you to import CAP alerts published in the standard CAP XML from external sources. To import CAP alerts, navigate to CAP Alerts > Import CAP Alert. You can import CAP alerts from a URL, Copied XML text or from a file.

Import CAP Alert

After loading and previewing the CAP alert, you can create a draft of the alert by clicking on the Create Draft button. This will create a draft of the alert that you can edit and publish.

Import CAP Alert

6. Signing CAP Alerts

You can provide a certificate and private key to sign the CAP XML alerts. These can be put in the CAP_TLS_VOLUME directory, and named as cert.pem and privkey.pem respectively. The CAP_TLS_VOLUME directory is mounted to /app/tls inside the container.

Then you will need to update the CAP_CERT_PATH and CAP_PRIVATE_KEY_PATH environment variables to point to absolute paths of the cert and private key files respectively, as accessible inside the container.

For example, if the cert and private key files are placed on the root of CAP_TLS_VOLUME directory, the CAP_CERT_PATH and CAP_PRIVATE_KEY_PATH should be set to /app/tls/cert.pem and /app/tls/privkey.pem respectively.

If you do not have a certificate and private key, you can generate a self-signed certificate and private key using the following commands, and place them in the CAP_TLS_VOLUME directory.

openssl req -x509 -nodes -subj "/CN=<ip-or-domain>" -days 365 -newkey rsa -keyout privkey.pem -out cert.pem

NOTE: Make sure to replace <ip-or-domain> with the IP address or domain name of the site.

Development

To test new features, begin by following the installation steps.

If any changes are made to the models, the database must also be updated. This can be done as follows:

docker exec cap_web python manage.py makemigrations

(creates new migration files based on changes to the Django models.)

docker exec cap_web python manage.py migrate

(applies the migrations to the database.)

About

Running the Wagtail based CAP Composer in a standalone Wagtail site

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published