Development environment
For evaluation and development a development environment with a preconfigured example setup is provided. It includes preconfigured instances of Particiapi server, the Particiapp reference frontend, all Polis services, a PostgreSQL database, Keycloak (OpenID Connect identity provider), a pgAdmin (database frontend), and Maildev (SMTP test server).
Setup
Clone the particiapp-docker repository including its git submodules if needed:
git clone --recurse-submodules https://gitlab.com/particiapp/particiapp-docker.git
If you have already cloned the particiapp-docker project itself, check out the submodules:
git submodule update --init
Running the container environment
Ensure that you have installed Docker and that the Docker daemon is running.
Run the following command to build and run the containers:
cd particiapp-docker && docker compose --env-file dev.env -f docker-compose.yaml -f docker-compose.dev.yaml up
For development purposes (see Development below) it is recommended to use Docker Compose Watch by running the following command instead:
cd particiapp-docker && docker compose --env-file dev.env -f docker-compose.yaml -f docker-compose.dev.yaml up --watch
Configuring your web browser
The development environment simulates a deployment scenario where the Polis and Particiapp frontends, the Particiapi server (and all other services) are served from different domains via HTTPS in order to allow for testing CORS. DNS resolution is provided accordingly and no services except a SOCKS5 proxy are directly exposed to the host. Web browsers and other HTTP clients must thus be configured to use the SOCKS5 proxy listening on port 1080 in order to access any of the services attached to the Docker network and also use this proxy for DNS resolution. When the Docker compose environment is started for the first time, self-signed certificates will be generated for all of the above services. Make sure to visit all of them and add exceptions for them in your browser.
Chrome
The Chrome web browser must be started with the following command line options in order to use the poxy listening on localhost: --proxy-server="socks5://127.0.0.1:1080" --host-resolver-rules='MAP * ~NOTFOUND, EXCLUDE 127.0.0.1'
When visiting any of the above URLs for the first time you will need to add an exception for the self-signed certificates as follows:
Firefox
In Firefox open "Settings" from the menu, in the "General" panel go to the "Network Settings" section and click on the "Settings…" button.
Select "Manual proxy configuration" and fill in "127.0.0.1" as the "SOCKS Host" and "1080" as the "Port", select "SOCKS v5" and "Proxy DNS when using SOCKS v5" below.
When visiting any of the above URLs for the first time you will need to add an exception for the self-signed certificates as follows:
Safari
In Safari open "Settings" from the menu, in the "Advanced" panel go to Proxys than choose "Change Settings" as follows:
Services
The following services are made available:
| Service | URL | Comment |
|---|---|---|
| Polis frontend | https://polis.example.org/ | Sign up for a new user account in order to add conversations |
| Particiapi server | https://particiapi.example.org/ | |
| Particiapp reference frontend | https://www.example.com/ | Participation frontend will ask for a conversation identifier from the Polis admin frontend |
| Keycloak | https://idp.example.net |
|
| pgAdmin | https://pgadmin.example.net |
|
| Maildev | https://maildev.example.net |
Development
For development purposes it is recommended to use Docker Compose Watch which will sync changed code into the respective container, trigger build processes and even rebuild and restart containers if necessary.
This means that you can edit files in any of the Particiapp projects which are checked out as submodules below the subprojects/ directory (Particiapi, Particiapp Web Client, Particiapp Web Components, Particiapp Reference Frontend) and changes will take effect immediately.
In order to develop a branded frontend based on Particiapp reference frontend you can take the example-frontend/ directory or the Particiapp example frontend as a starting point and point the PARTICIAPP_FRONTEND_DIR variable in your .env file to it. Any changes will trigger a rebuild of the frontend and changes to package.json will trigger a rebuild of the container ensuring npm dependencies are up to date.