From 183aa0a848f24ed86931ad181c0ae4188ad83997 Mon Sep 17 00:00:00 2001 From: Zikani Nyirenda Mwase Date: Fri, 10 Oct 2025 05:33:53 +0200 Subject: [PATCH 1/2] Streamline instructions and configuration files Moved the content of the README to the contributor file to make entry point clear and point straight to Confluence. Combined the .env.cache into the .env.example file and added more documentation for the cache in the example file. Removed empty database configuration file --- .env.cache.example | 6 --- .env.database.example | 0 .env.example | 42 +++++++++++++-- .github/workflows/ci.yaml | 1 - CONTRIBUTOR.md | 108 +++++++++++++++++++++++++++++++++++++ README.md | 110 +++----------------------------------- compose.cache.yml | 2 +- compose.yml | 2 - deploy_openimis.sh | 2 - 9 files changed, 153 insertions(+), 120 deletions(-) delete mode 100644 .env.cache.example delete mode 100644 .env.database.example create mode 100644 CONTRIBUTOR.md diff --git a/.env.cache.example b/.env.cache.example deleted file mode 100644 index 6bd6dcc..0000000 --- a/.env.cache.example +++ /dev/null @@ -1,6 +0,0 @@ -REDIS_PASSWORD=redisUserPass123 -CACHE_BACKEND=django.core.cache.backends.redis.RedisCache -CACHE_URL=redis://:${REDIS_PASSWORD}@redis:6379 -CACHE_OPTIONS={} -CACHE_OBJECT_DEFAULT=True -CACHE_OBJECT_TTL=3600 \ No newline at end of file diff --git a/.env.database.example b/.env.database.example deleted file mode 100644 index e69de29..0000000 diff --git a/.env.example b/.env.example index 62c853f..c1074f8 100644 --- a/.env.example +++ b/.env.example @@ -1,13 +1,19 @@ # docker-compose parameters # docker compose project name PROJECT_NAME=demo -# urls # url of openimis, FQDN DOMAIN=demo.openimis.org # allowed host for CORS and CSFR, coma sepataed values HOSTS=${DOMAIN} +CSRF_TRUSTED_ORIGINS=http://localhost + +# Secret Key is used for generating JWT authentication tokens, +# Make sure to use a strong key +SECRET_KEY= + # http port for openimis HTTP_PORT=80 + # https port for openimis HTTPS_PORT=443 @@ -52,6 +58,34 @@ DJANGO_LOG_HANDLER=debug-log # should the database be migrated at every container startup. Will be done anyway if $SITE_ROOT=api DJANGO_MIGRATE=True -CSRF_TRUSTED_ORIGINS=http://localhost -# should define a strong key for JWT token key -SECRET_KEY= + +###################### +# Cache Configuration +###################### +# +# Below are keys for configuring Caching in openIMIS +# openIMIS supports caching via Redis or Local cache or any cache backens supported by Django +# +# Uncomment the keys below to configure +## Cache Backend - specifies which cache backend to use +## +## local - django.core.cache.backends.locmem.LocMemCache +## redis - django.core.cache.backends.redis.RedisCache (default) +CACHE_BACKEND=django.core.cache.backends.redis.RedisCache + +## Redis Password for the redis caching +REDIS_PASSWORD=redisUserPass123 + +## URL for the cache, +# For redis format must be redis://:${REDIS_PASSWORD}@redisaddr:redisport +CACHE_URL=redis://:${REDIS_PASSWORD}@redis:6379 + +## Cache Options +## See: https:// +CACHE_OPTIONS={} + +## Whether to cache objects by default +CACHE_OBJECT_DEFAULT=True + +## The Time-To-Live for cached objects +CACHE_OBJECT_TTL=3600 \ No newline at end of file diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index bb43bf7..dabbb05 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -44,7 +44,6 @@ jobs: echo 'DEMO_DATASET=true' >> .env echo 'BE_TAG=develop' >> .env echo 'FE_TAG=develop' >> .env - cp .env.cache.example .env.cache cp .env.openSearch.example .env.openSearch cp .env.database.example .env.database diff --git a/CONTRIBUTOR.md b/CONTRIBUTOR.md new file mode 100644 index 0000000..dd543a4 --- /dev/null +++ b/CONTRIBUTOR.md @@ -0,0 +1,108 @@ +# CONTRIBUTING + + This repository provides a Docker package for openIMIS that includes all components to quickly setup, test and demo the solution. + + + If you are only looking to setup and test the solution please look for further instructions on the [openIMIS Wiki](https://openimis.atlassian.net/wiki/spaces/OP/pages/963182705/MO1.1+Install+the+modular+openIMIS+using+Docker) + + + The openIMIS docker compose currently includes the database, backend and worker, frontend, and third parties components (Lightning, OpenSearch, RabbitMQ, etc.). + + +In case of troubles, please contact our service desk via our [ticketing platform](https://openimis.atlassian.net/servicedesk/customer). + +## Prerequisite + +* Docker installed + +## Fast lane + +You can use the script `deploy_openimis.sh` to initialise all components (uses PostgreSQL DB). + +## First startup + +* Copy `.env.example` to `.env` and make the necessary adjustments. +* Choose a database default system to use. The default is PostgreSQL (`DB_DEFAULT=postgresql`, `DB_PORT=5432`), but you can also use MSSQL (`DB_DEFAULT=mssql`, `DB_PORT=1433`, `ACCEPT_EULA=Y`). +* Uncomment the line `DEMO_DATASET=true` in `.env` to initialise the database with the DEMO dataset. If you leave it commented, an empty openIMIS database will be created. + +## OpenFN/Lightning setup + +If the implementation involves managing the social protection workflow/import, then OpenFN/Lightning must be set up with the following steps: + +* Copy `.env.lightning.example` to `.env.lightning` and make the necessary adjustments. +* Create the `lightning_dev` database in the database container. +* Build the container: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml build lightning`. +* Run migrations: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml run --rm lightning mix ecto.migrate`. +* Set up the IMIS demo: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml run --rm lightning ./imisSetup.sh`. +* Start the service: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml up lightning`. + +## OpenSearch/OpenSearch Dashboards setup + +Both OpenSearch and OpenSearch Dashboards are not by default enabled in dockerized instance. To make them work, it's required to: + + * Copy `.env.openSearch.example` to `.env.openSearch` and make adjustments + * Run container build `docker compose -f docker-compose.yml -f docker-compose.openSearch.yml build opensearch opensearch-dashboards nginx` + * Run service `docker compose -f docker-compose.yml -f docker-compose.openSearch.yml up opensearch opensearch-dashboards nginx` + +This build provides also additional nginx proxy server in order to handle OpenSearch Dashboard application on frontend level. + +To run on a dockerized instance of openIMIS (database, backend, and frontend), including OpenSearch, please follow the steps below: + + * Add a value for the OPENSEARCH_BASIC_TOKEN in the environment (`.env`) file. This should be based on the admin and password credentials for OpenSearch. + * In the `.env` file in openimis-fe_js, use the following environment variable: `ENV OPENSEARCH_PROXY_ROOT="opensearch"`. + * Run the backend and frontend services. + +## Run openIMIS with Docker + +You can run the docker compose commands from within `openimis-dist_dkr` folder. + +### Pull new images + +To pull new images or images update `docker-compose pull` + +### Start / Stop + +* To start or restart all docker containers: `docker-compose start` +* To stop all docker containers: `docker-compose stop` + +## Create LetsEncrypt certificates + +Use the certbot docker compose file. + +`export DOMAIN [domain_name]` + +### Dry run + +`docker-compose run --rm --entrypoint " certbot certonly --webroot -w /var/www/certbot --staging --register-unsafely-without-email -d ${DOMAIN} --rsa-key-size 2048 --agree-tos --force-renewal" certbot` + +### Actual setup + +`docker-compose run --rm --entrypoint " certbot certonly --webroot -w /var/www/certbot --register-unsafely-without-email -d ${DOMAIN} --rsa-key-size 2048 --agree-tos --force-renewal" certbot` + + +## Run integration tests + +Integration tests live in the `/cypress` folder of this repo. + +### Requirements + +Ensure npm is installed, then install the required dependencies: + +`npm install` + +### Run e2e tests against local docker containers + +Make sure all expected containers are running: `docker ps`; +if not, start them with `docker compose start`. Then run tests: + +Headless: `npx cypress run` +Headed: `npx cypress open` or `npm run cy:open` + +### Run e2e tests against any local or remote url + +This can be useful for local development or verifying a staging deployment, +for example, if the target host is localhost:3000, +pass it into the corresponding test command with `-- --config "baseUrl=http://localhost:3000"`: + +- Headless: `npx cypress run --config "baseUrl=http://localhost:3000"` +- Headed: `npx cypress open --config "baseUrl=http://localhost:3000"` diff --git a/README.md b/README.md index 32142cf..b8263f6 100644 --- a/README.md +++ b/README.md @@ -1,108 +1,10 @@ -# openIMIS dockerized +
+openIMIS logo +
- This repository provides a Docker package for openIMIS that includes all components to quickly setup, test and demo the solution. - +# openIMIS Distribution - Please look for further instructions on the openIMIS Wiki: https://openimis.atlassian.net/wiki/spaces/OP/pages/963182705/MO1.1+Install+the+modular+openIMIS+using+Docker +This repository provides configuration files for deploying openIMIS via Docker. This is intended to help you setup all components to quickly setup, test and evaluate the solution. - - The openIMIS docker compose currently includes the database, backend and worker, frontend, and third parties components (Lightning, OpenSearch, RabbitMQ, etc.). - +Detailed instructions are in our Wiki: [Installation Guide](https://openimis.atlassian.net/wiki/spaces/OP/pages/963182705/MO1.1+Install+the+modular+openIMIS+using+Docker) -In case of troubles, please contact our service desk via our [ticketing platform](https://openimis.atlassian.net/servicedesk/customer). - -## Prerequisite - -* Docker installed - -## Fast lane - -You can use the script `deploy_openimis.sh` to initialise all components (uses PostgreSQL DB). - -## First startup - -* Copy `.env.example` to `.env` and make the necessary adjustments. -* Choose a database default system to use. The default is PostgreSQL (`DB_DEFAULT=postgresql`, `DB_PORT=5432`), but you can also use MSSQL (`DB_DEFAULT=mssql`, `DB_PORT=1433`, `ACCEPT_EULA=Y`). -* Uncomment the line `DEMO_DATASET=true` in `.env` to initialise the database with the DEMO dataset. If you leave it commented, an empty openIMIS database will be created. - -## OpenFN/Lightning setup - -If the implementation involves managing the social protection workflow/import, then OpenFN/Lightning must be set up with the following steps: - -* Copy `.env.lightning.example` to `.env.lightning` and make the necessary adjustments. -* Create the `lightning_dev` database in the database container. -* Build the container: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml build lightning`. -* Run migrations: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml run --rm lightning mix ecto.migrate`. -* Set up the IMIS demo: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml run --rm lightning ./imisSetup.sh`. -* Start the service: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml up lightning`. - -## OpenSearch/OpenSearch Dashboards setup - -Both OpenSearch and OpenSearch Dashboards are not by default enabled in dockerized instance. To make them work, it's required to: - - * Copy `.env.openSearch.example` to `.env.openSearch` and make adjustments - * Run container build `docker compose -f docker-compose.yml -f docker-compose.openSearch.yml build opensearch opensearch-dashboards nginx` - * Run service `docker compose -f docker-compose.yml -f docker-compose.openSearch.yml up opensearch opensearch-dashboards nginx` - -This build provides also additional nginx proxy server in order to handle OpenSearch Dashboard application on frontend level. - -To run on a dockerized instance of openIMIS (database, backend, and frontend), including OpenSearch, please follow the steps below: - - * Add a value for the OPENSEARCH_BASIC_TOKEN in the environment (`.env`) file. This should be based on the admin and password credentials for OpenSearch. - * In the `.env` file in openimis-fe_js, use the following environment variable: `ENV OPENSEARCH_PROXY_ROOT="opensearch"`. - * Run the backend and frontend services. - -## Run openIMIS with Docker - -You can run the docker compose commands from within `openimis-dist_dkr` folder. - -### Pull new images - -To pull new images or images update `docker-compose pull` - -### Start / Stop - -* To start or restart all docker containers: `docker-compose start` -* To stop all docker containers: `docker-compose stop` - -## Create LetsEncrypt certificates - -Use the certbot docker compose file. - -`export DOMAIN [domain_name]` - -### Dry run - -`docker-compose run --rm --entrypoint " certbot certonly --webroot -w /var/www/certbot --staging --register-unsafely-without-email -d ${DOMAIN} --rsa-key-size 2048 --agree-tos --force-renewal" certbot` - -### Actual setup - -`docker-compose run --rm --entrypoint " certbot certonly --webroot -w /var/www/certbot --register-unsafely-without-email -d ${DOMAIN} --rsa-key-size 2048 --agree-tos --force-renewal" certbot` - - -## Run integration tests - -Integration tests live in the `/cypress` folder of this repo. - -### Requirements - -Ensure npm is installed, then install the required dependencies: - -`npm install` - -### Run e2e tests against local docker containers - -Make sure all expected containers are running: `docker ps`; -if not, start them with `docker compose start`. Then run tests: - -Headless: `npx cypress run` -Headed: `npx cypress open` or `npm run cy:open` - -### Run e2e tests against any local or remote url - -This can be useful for local development or verifying a staging deployment, -for example, if the target host is localhost:3000, -pass it into the corresponding test command with `-- --config "baseUrl=http://localhost:3000"`: - -- Headless: `npx cypress run --config "baseUrl=http://localhost:3000"` -- Headed: `npx cypress open --config "baseUrl=http://localhost:3000"` diff --git a/compose.cache.yml b/compose.cache.yml index de0f264..079b898 100644 --- a/compose.cache.yml +++ b/compose.cache.yml @@ -9,7 +9,7 @@ services: - redis-database:/data - ./conf/redis/redis.conf:/usr/local/etc/redis/redis.conf env_file: - - ".env.cache" + - ".env" environment: - REDIS_PASSWORD=${REDIS_PASSWORD} - REDIS_PORT=6379 diff --git a/compose.yml b/compose.yml index b5301b5..8bff140 100644 --- a/compose.yml +++ b/compose.yml @@ -4,7 +4,6 @@ include: - path: compose.base.yml env_file: - .env - - .env.cache - .env.openSearch - path: compose.openSearch.yml env_file: @@ -13,7 +12,6 @@ include: - path: compose.cache.yml env_file: - .env - - .env.cache # - path: compose.certbot.yml diff --git a/deploy_openimis.sh b/deploy_openimis.sh index 2604c73..28b14ad 100644 --- a/deploy_openimis.sh +++ b/deploy_openimis.sh @@ -6,9 +6,7 @@ echo "Using existing env files" else echo "creating env files from example" cp .env.example .env -cp .cache.example .env.cache cp .env.openSearch.example .env.openSearch -cp .env.database.example .env.database fi From b12cbac75dcde7f85b6f40ea06164a2327ab8c96 Mon Sep 17 00:00:00 2001 From: Zikani Nyirenda Mwase Date: Fri, 10 Oct 2025 06:12:43 +0200 Subject: [PATCH 2/2] chore: remove .env.database reference in gh action --- .github/workflows/ci.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index dabbb05..080bd26 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -45,7 +45,6 @@ jobs: echo 'BE_TAG=develop' >> .env echo 'FE_TAG=develop' >> .env cp .env.openSearch.example .env.openSearch - cp .env.database.example .env.database docker compose up -d