Skip to content

Commit 8d68d6d

Browse files
unteemunteem
committed
📝(doc): add documentation to install with compose
Signed-off-by: unteem <timothee@indie.host> f
1 parent de8e812 commit 8d68d6d

File tree

21 files changed

+812
-0
lines changed

21 files changed

+812
-0
lines changed

‎docker/files/production/etc/nginx/conf.d/default.conf.template

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
upstream docs_backend {
2+
server ${BACKEND_HOST}:8000 fail_timeout=0;
3+
}
4+
5+
upstream docs_frontend {
6+
server ${FRONTEND_HOST}:3000 fail_timeout=0;
7+
}
8+
9+
server {
10+
listen 8083;
11+
server_name localhost;
12+
charset utf-8;
13+
14+
# Disables server version feedback on pages and in headers
15+
server_tokens off;
16+
17+
proxy_ssl_server_name on;
18+
19+
location @proxy_to_docs_backend {
20+
proxy_set_header Host $http_host;
21+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
22+
23+
proxy_redirect off;
24+
proxy_pass http://docs_backend;
25+
}
26+
27+
location @proxy_to_docs_frontend {
28+
proxy_set_header Host $http_host;
29+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
30+
31+
proxy_redirect off;
32+
proxy_pass http://docs_frontend;
33+
}
34+
35+
location / {
36+
try_files $uri @proxy_to_docs_frontend;
37+
}
38+
39+
location /api {
40+
try_files $uri @proxy_to_docs_backend;
41+
}
42+
43+
location /admin {
44+
try_files $uri @proxy_to_docs_backend;
45+
}
46+
47+
# Proxy auth for media
48+
location /media/ {
49+
# Auth request configuration
50+
auth_request /media-auth;
51+
auth_request_set $authHeader $upstream_http_authorization;
52+
auth_request_set $authDate $upstream_http_x_amz_date;
53+
auth_request_set $authContentSha256 $upstream_http_x_amz_content_sha256;
54+
55+
# Pass specific headers from the auth response
56+
proxy_set_header Authorization $authHeader;
57+
proxy_set_header X-Amz-Date $authDate;
58+
proxy_set_header X-Amz-Content-SHA256 $authContentSha256;
59+
60+
# Get resource from Minio
61+
proxy_pass https://${S3_HOST}/${BUCKET_NAME}/;
62+
proxy_set_header Host ${S3_HOST};
63+
64+
proxy_ssl_name ${S3_HOST};
65+
66+
add_header Content-Security-Policy "default-src 'none'" always;
67+
}
68+
69+
location /media-auth {
70+
proxy_pass http://docs_backend/api/v1.0/documents/media-auth/;
71+
proxy_set_header Host $host;
72+
proxy_set_header X-Real-IP $remote_addr;
73+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
74+
proxy_set_header X-Original-URL $request_uri;
75+
76+
# Prevent the body from being passed
77+
proxy_pass_request_body off;
78+
proxy_set_header Content-Length "";
79+
proxy_set_header X-Original-Method $request_method;
80+
}
81+
}

‎docs/examples/compose/compose.yaml

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
services:
2+
postgresql:
3+
image: postgres:16
4+
healthcheck:
5+
test: ["CMD", "pg_isready", "-q", "-U", "docs", "-d", "docs"]
6+
interval: 1s
7+
timeout: 2s
8+
retries: 300
9+
env_file:
10+
- env.d/postgresql
11+
- env.d/common
12+
environment:
13+
- PGDATA=/var/lib/postgresql/data/pgdata
14+
volumes:
15+
- ./data/databases/backend:/var/lib/postgresql/data/pgdata
16+
17+
redis:
18+
image: redis:5
19+
20+
backend:
21+
image: lasuite/impress-backend:latest
22+
user: ${DOCKER_USER:-1000}
23+
restart: always
24+
environment:
25+
- DJANGO_CONFIGURATION=Production
26+
env_file:
27+
- env.d/backend
28+
- env.d/postgresql
29+
- env.d/common
30+
healthcheck:
31+
test: ["CMD", "python", "manage.py", "check"]
32+
interval: 15s
33+
timeout: 30s
34+
retries: 20
35+
start_period: 10s
36+
depends_on:
37+
postgresql:
38+
condition: service_healthy
39+
restart: true
40+
redis:
41+
condition: service_started
42+
43+
y-provider:
44+
image: lasuite/impress-y-provider:latest
45+
user: ${DOCKER_USER:-1000}
46+
env_file:
47+
- env.d/yprovider
48+
- env.d/common
49+
50+
frontend:
51+
image: lasuite/impress-frontend:latest
52+
user: "101"
53+
env_file:
54+
- env.d/common
55+
# Uncomment and set your values if using our nginx proxy example
56+
#environment:
57+
# - VIRTUAL_HOST=${DOCS_HOST} # used by nginx proxy
58+
# - VIRTUAL_PORT=8083 # used by nginx proxy
59+
# - LETSENCRYPT_HOST=${DOCS_HOST} # used by lets encrypt to generate TLS certificate
60+
volumes:
61+
- ./default.conf.template:/etc/nginx/templates/default.conf.template
62+
depends_on:
63+
backend:
64+
condition: service_healthy
65+
# Uncomment if using our nginx proxy example
66+
# networks:
67+
# - proxy-tier
68+
# - default
69+
70+
# Uncomment if using our nginx proxy example
71+
#networks:
72+
# proxy-tier:
73+
# external: true

‎docs/examples/compose/keycloak/README.md

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Deploy and Configure Keycloak for Docs
2+
3+
## Installation
4+
5+
> \[!CAUTION\]
6+
> We provide those instructions as an example, for production environments, you should follow the [official documentation](https://www.keycloak.org/documentation).
7+
8+
### Step 1: Prepare your working environment:
9+
10+
```bash
11+
mkdir keycloak
12+
curl -o compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/keycloak/compose.yaml
13+
curl -o env.d/kc_postgresql https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/env.d/production/kc_postgresql
14+
curl -o env.d/keycloak https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/env.d/production/keycloak
15+
```
16+
17+
### Step 2:. Update `env.d/` files
18+
19+
The following variables need to be updated with your own values, others can be left as is:
20+
21+
```env
22+
POSTGRES_PASSWORD=<generate postgres password>
23+
KC_HOSTNAME=https://id.yourdomain.tld # Change with your own URL
24+
KC_BOOTSTRAP_ADMIN_PASSWORD=<generate your password>
25+
```
26+
27+
### Step 3: Expose keycloak instance on https
28+
29+
> \[!NOTE\]
30+
> You can skip this section if you already have your own setup.
31+
32+
To access your Keycloak instance on the public network, it needs to be exposed on a domain with SSL termination. You can use our [example with nginx proxy and Let's Encrypt companion](../nginx-proxy/README.md) for automated creation/renewal of certificates using [acme.sh](http://acme.sh).
33+
34+
If following our example, uncomment the environment and network sections in compose file and update it with your values.
35+
36+
```yaml
37+
version: '3'
38+
services:
39+
keycloak:
40+
...
41+
# Uncomment and set your values if using our nginx proxy example
42+
# environment:
43+
# - VIRTUAL_HOST=id.yourdomain.tld # used by nginx proxy
44+
# - VIRTUAL_PORT=8080 # used by nginx proxy
45+
# - LETSENCRYPT_HOST=id.yourdomain.tld # used by lets encrypt to generate TLS certificate
46+
...
47+
# Uncomment if using our nginx proxy example
48+
# networks:
49+
# - proxy-tier
50+
# - default
51+
52+
# Uncomment if using our nginx proxy example
53+
#networks:
54+
# proxy-tier:
55+
# external: true
56+
```
57+
58+
### Step 4: Start the service
59+
60+
```bash
61+
`docker compose up -d`
62+
```
63+
64+
Your keycloak instance is now available on https://doc.yourdomain.tld
65+
66+
## Creating an OIDC Client for Docs Application
67+
68+
### Step 1: Create a New Realm
69+
70+
1. Log in to the Keycloak administration console.
71+
2. Navigate to the realm tab and click on the "Create realm" button.
72+
3. Enter the name of the realm - `docs`.
73+
4. Click "Create".
74+
75+
#### Step 2: Create a New Client
76+
77+
1. Navigate to the "Clients" tab.
78+
2. Click on the "Create client" button.
79+
3. Enter the client ID - e.g. `docs`.
80+
4. Enable "Client authentification" option.
81+
6. Set the "Valid redirect URIs" to the URL of your docs application suffixed with `/*` - e.g., "https://docs.example.com/*".
82+
1. Set the "Web Origins" to the URL of your docs application - e.g. `https://docs.example.com`.
83+
1. Click "Save".
84+
85+
#### Step 3: Get Client Credentials
86+
87+
1. Go to the "Credentials" tab.
88+
2. Copy the client ID (`docs` in this example) and the client secret.

‎docs/examples/compose/keycloak/compose.yaml

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
services:
2+
kc_postgresql:
3+
image: postgres:16
4+
healthcheck:
5+
test: ["CMD", "pg_isready", "-q", "-U", "keycloak", "-d", "keycloak"]
6+
interval: 1s
7+
timeout: 2s
8+
retries: 300
9+
env_file:
10+
- env.d/kc_postgresql
11+
volumes:
12+
- ./data/keycloak:/var/lib/postgresql/data/pgdata
13+
14+
keycloak:
15+
image: quay.io/keycloak/keycloak:26.1.3
16+
command: ["start"]
17+
env_file:
18+
- env.d/kc_postgresql
19+
- env.d/keycloak
20+
# Uncomment and set your values if using our nginx proxy example
21+
# environment:
22+
# - VIRTUAL_HOST=id.yourdomain.tld # used by nginx proxy
23+
# - VIRTUAL_PORT=8080 # used by nginx proxy
24+
# - LETSENCRYPT_HOST=id.yourdomain.tld # used by lets encrypt to generate TLS certificate
25+
depends_on:
26+
kc_postgresql::
27+
condition: service_healthy
28+
restart: true
29+
# Uncomment if using our nginx proxy example
30+
# networks:
31+
# - proxy-tier
32+
# - default
33+
#
34+
#networks:
35+
# proxy-tier:
36+
# external: true

‎docs/examples/compose/minio/README.md

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Deploy and Configure Minio for Docs
2+
3+
## Installation
4+
5+
> \[!CAUTION\]
6+
> We provide those instructions as an example, it should not be run in production. For production environments, deploy MinIO [in a Multi-Node Multi-Drive (Distributed)](https://min.io/docs/minio/linux/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.html#minio-mnmd) topology
7+
8+
### Step 1: Prepare your working environment:
9+
10+
```bash
11+
mkdir minio
12+
curl -o compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/minio/compose.yaml
13+
```
14+
15+
### Step 2:. Update compose file with your own values
16+
17+
```yaml
18+
version: '3'
19+
services:
20+
minio:
21+
...
22+
environment:
23+
- MINIO_ROOT_USER=<Set minio root username>
24+
- MINIO_ROOT_PASSWORD=<Set minio root password>
25+
```
26+
27+
### Step 3: Expose MinIO instance
28+
29+
#### Option 1: Internal network
30+
31+
You may not need to expose your MinIO instance to the public if only services hosted on the same private network need to access to your MinIO instance.
32+
33+
You should create a docker network that will be shared between those services
34+
35+
```bash
36+
docker network create storage-tier
37+
```
38+
39+
#### Option 2: Public network
40+
41+
If you want to expose your MinIO instance to the public, it needs to be exposed on a domain with SSL termination. You can use our [example](../nginx-proxy/README.md) with an nginx proxy and Let's Encrypt companion for automated creation/renewal of Let's Encrypt certificates using [acme.sh](http://acme.sh).
42+
43+
If following our example, uncomment the environment and network sections in compose file and update it with your values.
44+
45+
```yaml
46+
version: '3'
47+
services:
48+
docs:
49+
...
50+
minio:
51+
...
52+
environment:
53+
...
54+
# - VIRTUAL_HOST=storage.yourdomain.tld # used by nginx proxy
55+
# - VIRTUAL_PORT=9000 # used by nginx proxy
56+
# - LETSENCRYPT_HOST=storage.yourdomain.tld # used by lets encrypt to generate TLS certificate
57+
...
58+
# Uncomment if using our nginx proxy example
59+
# networks:
60+
# - proxy-tier
61+
# - default
62+
63+
# Uncomment if using our nginx proxy example
64+
#networks:
65+
# proxy-tier:
66+
# external: true
67+
```
68+
69+
In this example we are only exposing MinIO API service. Follow the official documentation to configure Minio WebUI.
70+
71+
### Step 4: Start the service
72+
73+
```bash
74+
`docker compose up -d`
75+
```
76+
77+
Your minio instance is now available on https://storage.yourdomain.tld
78+
79+
## Creating a user and bucket for your Docs instance
80+
81+
### Installing mc
82+
83+
Follow the [official documentation](https://min.io/docs/minio/linux/reference/minio-mc.html#install-mc) to install mc
84+
85+
### Step 1: Configure `mc` to connect to your MinIO Server with your root user
86+
87+
```shellscript
88+
mc alias set minio <MINIO_SERVER_URL> <MINIO_ROOT_USER> <MINIO_ROOT_PASSWORD>
89+
```
90+
91+
Replace the values with those you have set in the previous steps
92+
93+
### Step 2: Create a new bucket with versioning enabled
94+
95+
```shellscript
96+
mc mb --with-versioning minio/<your-bucket-name>
97+
```
98+
99+
Replace `your-bucket-name` with the desired name for your bucket e.g. `docs-media-storage`
100+
101+
### Additional notes:
102+
103+
For increased security you should create a dedicated user with `readwrite` access to the Bucket. In the following example we will use MinIO root user.

0 commit comments

Comments
 (0)