Skip to content

Commit ddc7ac5

Browse files
zikani03zikani03
authored
Merge pull request #80 from openimis/OP-2616-improve-documentation
Streamline instructions and configuration files
2 parents e9bb332 + b12cbac commit ddc7ac5

File tree

9 files changed

+153
-121
lines changed

9 files changed

+153
-121
lines changed

‎.env.cache.example‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎.env.database.example‎

Whitespace-only changes.

‎.env.example‎

Lines changed: 38 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,19 @@
11
# docker-compose parameters
22
# docker compose project name
33
PROJECT_NAME=demo
4-
# urls
54
# url of openimis, FQDN
65
DOMAIN=demo.openimis.org
76
# allowed host for CORS and CSFR, coma sepataed values
87
HOSTS=${DOMAIN}
8+
CSRF_TRUSTED_ORIGINS=http://localhost
9+
10+
# Secret Key is used for generating JWT authentication tokens,
11+
# Make sure to use a strong key
12+
SECRET_KEY=
13+
914
# http port for openimis
1015
HTTP_PORT=80
16+
1117
# https port for openimis
1218
HTTPS_PORT=443
1319

@@ -52,6 +58,34 @@ DJANGO_LOG_HANDLER=debug-log
5258
# should the database be migrated at every container startup. Will be done anyway if $SITE_ROOT=api
5359
DJANGO_MIGRATE=True
5460

55-
CSRF_TRUSTED_ORIGINS=http://localhost
56-
# should define a strong key for JWT token key
57-
SECRET_KEY=
61+
62+
######################
63+
# Cache Configuration
64+
######################
65+
#
66+
# Below are keys for configuring Caching in openIMIS
67+
# openIMIS supports caching via Redis or Local cache or any cache backens supported by Django
68+
#
69+
# Uncomment the keys below to configure
70+
## Cache Backend - specifies which cache backend to use
71+
##
72+
## local - django.core.cache.backends.locmem.LocMemCache
73+
## redis - django.core.cache.backends.redis.RedisCache (default)
74+
CACHE_BACKEND=django.core.cache.backends.redis.RedisCache
75+
76+
## Redis Password for the redis caching
77+
REDIS_PASSWORD=redisUserPass123
78+
79+
## URL for the cache,
80+
# For redis format must be redis://:${REDIS_PASSWORD}@redisaddr:redisport
81+
CACHE_URL=redis://:${REDIS_PASSWORD}@redis:6379
82+
83+
## Cache Options
84+
## See: https://
85+
CACHE_OPTIONS={}
86+
87+
## Whether to cache objects by default
88+
CACHE_OBJECT_DEFAULT=True
89+
90+
## The Time-To-Live for cached objects
91+
CACHE_OBJECT_TTL=3600

‎.github/workflows/ci.yaml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,9 +44,7 @@ jobs:
4444
echo 'DEMO_DATASET=true' >> .env
4545
echo 'BE_TAG=develop' >> .env
4646
echo 'FE_TAG=develop' >> .env
47-
cp .env.cache.example .env.cache
4847
cp .env.openSearch.example .env.openSearch
49-
cp .env.database.example .env.database
5048
5149
docker compose up -d
5250

‎CONTRIBUTOR.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# CONTRIBUTING
2+
3+
This repository provides a Docker package for openIMIS that includes all components to quickly setup, test and demo the solution.
4+
5+
6+
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)
7+
8+
9+
The openIMIS docker compose currently includes the database, backend and worker, frontend, and third parties components (Lightning, OpenSearch, RabbitMQ, etc.).
10+
11+
12+
In case of troubles, please contact our service desk via our [ticketing platform](https://openimis.atlassian.net/servicedesk/customer).
13+
14+
## Prerequisite
15+
16+
* Docker installed
17+
18+
## Fast lane
19+
20+
You can use the script `deploy_openimis.sh` to initialise all components (uses PostgreSQL DB).
21+
22+
## First startup
23+
24+
* Copy `.env.example` to `.env` and make the necessary adjustments.
25+
* 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`).
26+
* 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.
27+
28+
## OpenFN/Lightning setup
29+
30+
If the implementation involves managing the social protection workflow/import, then OpenFN/Lightning must be set up with the following steps:
31+
32+
* Copy `.env.lightning.example` to `.env.lightning` and make the necessary adjustments.
33+
* Create the `lightning_dev` database in the database container.
34+
* Build the container: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml build lightning`.
35+
* Run migrations: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml run --rm lightning mix ecto.migrate`.
36+
* Set up the IMIS demo: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml run --rm lightning ./imisSetup.sh`.
37+
* Start the service: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml up lightning`.
38+
39+
## OpenSearch/OpenSearch Dashboards setup
40+
41+
Both OpenSearch and OpenSearch Dashboards are not by default enabled in dockerized instance. To make them work, it's required to:
42+
43+
* Copy `.env.openSearch.example` to `.env.openSearch` and make adjustments
44+
* Run container build `docker compose -f docker-compose.yml -f docker-compose.openSearch.yml build opensearch opensearch-dashboards nginx`
45+
* Run service `docker compose -f docker-compose.yml -f docker-compose.openSearch.yml up opensearch opensearch-dashboards nginx`
46+
47+
This build provides also additional nginx proxy server in order to handle OpenSearch Dashboard application on frontend level.
48+
49+
To run on a dockerized instance of openIMIS (database, backend, and frontend), including OpenSearch, please follow the steps below:
50+
51+
* 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.
52+
* In the `.env` file in openimis-fe_js, use the following environment variable: `ENV OPENSEARCH_PROXY_ROOT="opensearch"`.
53+
* Run the backend and frontend services.
54+
55+
## Run openIMIS with Docker
56+
57+
You can run the docker compose commands from within `openimis-dist_dkr` folder.
58+
59+
### Pull new images
60+
61+
To pull new images or images update `docker-compose pull`
62+
63+
### Start / Stop
64+
65+
* To start or restart all docker containers: `docker-compose start`
66+
* To stop all docker containers: `docker-compose stop`
67+
68+
## Create LetsEncrypt certificates
69+
70+
Use the certbot docker compose file.
71+
72+
`export DOMAIN [domain_name]`
73+
74+
### Dry run
75+
76+
`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`
77+
78+
### Actual setup
79+
80+
`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`
81+
82+
83+
## Run integration tests
84+
85+
Integration tests live in the `/cypress` folder of this repo.
86+
87+
### Requirements
88+
89+
Ensure npm is installed, then install the required dependencies:
90+
91+
`npm install`
92+
93+
### Run e2e tests against local docker containers
94+
95+
Make sure all expected containers are running: `docker ps`;
96+
if not, start them with `docker compose start`. Then run tests:
97+
98+
Headless: `npx cypress run`
99+
Headed: `npx cypress open` or `npm run cy:open`
100+
101+
### Run e2e tests against any local or remote url
102+
103+
This can be useful for local development or verifying a staging deployment,
104+
for example, if the target host is localhost:3000,
105+
pass it into the corresponding test command with `-- --config "baseUrl=http://localhost:3000"`:
106+
107+
- Headless: `npx cypress run --config "baseUrl=http://localhost:3000"`
108+
- Headed: `npx cypress open --config "baseUrl=http://localhost:3000"`

‎README.md‎

Lines changed: 6 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,10 @@
1-
# openIMIS dockerized
1+
<center>
2+
<img src="https://openimis.org/themes/custom/ffw/logo.svg" width="200px" alt="openIMIS logo" />
3+
</center>
24

3-
This repository provides a Docker package for openIMIS that includes all components to quickly setup, test and demo the solution.
4-
5+
# openIMIS Distribution
56

6-
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
7+
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.
78

8-
9-
The openIMIS docker compose currently includes the database, backend and worker, frontend, and third parties components (Lightning, OpenSearch, RabbitMQ, etc.).
10-
9+
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)
1110

12-
In case of troubles, please contact our service desk via our [ticketing platform](https://openimis.atlassian.net/servicedesk/customer).
13-
14-
## Prerequisite
15-
16-
* Docker installed
17-
18-
## Fast lane
19-
20-
You can use the script `deploy_openimis.sh` to initialise all components (uses PostgreSQL DB).
21-
22-
## First startup
23-
24-
* Copy `.env.example` to `.env` and make the necessary adjustments.
25-
* 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`).
26-
* 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.
27-
28-
## OpenFN/Lightning setup
29-
30-
If the implementation involves managing the social protection workflow/import, then OpenFN/Lightning must be set up with the following steps:
31-
32-
* Copy `.env.lightning.example` to `.env.lightning` and make the necessary adjustments.
33-
* Create the `lightning_dev` database in the database container.
34-
* Build the container: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml build lightning`.
35-
* Run migrations: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml run --rm lightning mix ecto.migrate`.
36-
* Set up the IMIS demo: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml run --rm lightning ./imisSetup.sh`.
37-
* Start the service: `docker compose -f docker-compose.yml -f docker-compose.lightning.yml up lightning`.
38-
39-
## OpenSearch/OpenSearch Dashboards setup
40-
41-
Both OpenSearch and OpenSearch Dashboards are not by default enabled in dockerized instance. To make them work, it's required to:
42-
43-
* Copy `.env.openSearch.example` to `.env.openSearch` and make adjustments
44-
* Run container build `docker compose -f docker-compose.yml -f docker-compose.openSearch.yml build opensearch opensearch-dashboards nginx`
45-
* Run service `docker compose -f docker-compose.yml -f docker-compose.openSearch.yml up opensearch opensearch-dashboards nginx`
46-
47-
This build provides also additional nginx proxy server in order to handle OpenSearch Dashboard application on frontend level.
48-
49-
To run on a dockerized instance of openIMIS (database, backend, and frontend), including OpenSearch, please follow the steps below:
50-
51-
* 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.
52-
* In the `.env` file in openimis-fe_js, use the following environment variable: `ENV OPENSEARCH_PROXY_ROOT="opensearch"`.
53-
* Run the backend and frontend services.
54-
55-
## Run openIMIS with Docker
56-
57-
You can run the docker compose commands from within `openimis-dist_dkr` folder.
58-
59-
### Pull new images
60-
61-
To pull new images or images update `docker-compose pull`
62-
63-
### Start / Stop
64-
65-
* To start or restart all docker containers: `docker-compose start`
66-
* To stop all docker containers: `docker-compose stop`
67-
68-
## Create LetsEncrypt certificates
69-
70-
Use the certbot docker compose file.
71-
72-
`export DOMAIN [domain_name]`
73-
74-
### Dry run
75-
76-
`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`
77-
78-
### Actual setup
79-
80-
`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`
81-
82-
83-
## Run integration tests
84-
85-
Integration tests live in the `/cypress` folder of this repo.
86-
87-
### Requirements
88-
89-
Ensure npm is installed, then install the required dependencies:
90-
91-
`npm install`
92-
93-
### Run e2e tests against local docker containers
94-
95-
Make sure all expected containers are running: `docker ps`;
96-
if not, start them with `docker compose start`. Then run tests:
97-
98-
Headless: `npx cypress run`
99-
Headed: `npx cypress open` or `npm run cy:open`
100-
101-
### Run e2e tests against any local or remote url
102-
103-
This can be useful for local development or verifying a staging deployment,
104-
for example, if the target host is localhost:3000,
105-
pass it into the corresponding test command with `-- --config "baseUrl=http://localhost:3000"`:
106-
107-
- Headless: `npx cypress run --config "baseUrl=http://localhost:3000"`
108-
- Headed: `npx cypress open --config "baseUrl=http://localhost:3000"`

‎compose.cache.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ services:
99
- redis-database:/data
1010
- ./conf/redis/redis.conf:/usr/local/etc/redis/redis.conf
1111
env_file:
12-
- ".env.cache"
12+
- ".env"
1313
environment:
1414
- REDIS_PASSWORD=${REDIS_PASSWORD}
1515
- REDIS_PORT=6379

‎compose.yml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@ include:
44
- path: compose.base.yml
55
env_file:
66
- .env
7-
- .env.cache
87
- .env.openSearch
98
- path: compose.openSearch.yml
109
env_file:
@@ -13,7 +12,6 @@ include:
1312
- path: compose.cache.yml
1413
env_file:
1514
- .env
16-
- .env.cache
1715
# - path: compose.certbot.yml
1816

1917

‎deploy_openimis.sh‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,7 @@ echo "Using existing env files"
66
else
77
echo "creating env files from example"
88
cp .env.example .env
9-
cp .cache.example .env.cache
109
cp .env.openSearch.example .env.openSearch
11-
cp .env.database.example .env.database
1210
fi
1311

1412

0 commit comments

Comments
 (0)