From 63b8a66ebbbc02bbf61425a3feaf28efa853e95d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Sat, 23 Nov 2024 01:09:57 +0100 Subject: [PATCH 1/9] Add restart policy to autostart the containers after boot --- compose.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/compose.yaml b/compose.yaml index 8182ea6..6eea7c7 100644 --- a/compose.yaml +++ b/compose.yaml @@ -1,5 +1,9 @@ +x-op-restart-policy: &restart_policy + restart: unless-stopped + services: shimatta-kenkyusho-web: + <<: *restart_policy build: . volumes: - "${DJANGO_STATIC_VOL:-./run/static}:/var/static" @@ -30,6 +34,7 @@ services: start_period: 30s shimatta-kenkyusho-db: + <<: *restart_policy image: postgres:16.5-alpine environment: POSTGRES_PASSWORD: "${DJANGO_POSTGRESQL_PW:-p4ssw0rd}" From b47c7ad38d5eaed6046acd194f96ed28e6e058a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Sat, 23 Nov 2024 01:10:23 +0100 Subject: [PATCH 2/9] Add readme. Rename example env, to unhide it in the fileexplorer. --- README.md | 185 ++++++++++++++++++++++++++++++++++++ .env.example => example.env | 0 2 files changed, 185 insertions(+) create mode 100644 README.md rename .env.example => example.env (100%) diff --git a/README.md b/README.md new file mode 100644 index 0000000..62ce03e --- /dev/null +++ b/README.md @@ -0,0 +1,185 @@ +# Shimatta Kenkyusho Parts Database + +## Installation + +### Prerequisites +Shimatta Kenkyusho (しまった・研究所) is a Django based web application. It is highly recommended to run it using the supplied docker setup. This removes the need of any special installation on the host system. This guide assumes, that `nginx` is running on the host system and can serve as a reverse proxy and webserver. For easiest download, it is recommended to clone the desired release with `git` + +Install the requirements: + +**For Debian / Ubuntu:** +``` +# apt-get update +# apt-get install docker docker-compose-plugin nginx git +``` + +**For Arch based Systems:** +``` +# pacman -S nginx docker docker-compose git +``` + +### Setup Shimatta Kenkyusho + +Clone this repository: +``` +$ git clone https://git.shimatta.de/mhu/shimatta-kenkyusho.git +``` + +> Note: Shimatta Kenkyusho is currently not stable yet and the newest verison is in the `develop` branch. This will change once actual releases are done and merged to the `master` branch. You will be alble to get the latest stable version from the `master` branch or a repsective tag. For now, the `develop` is recommended. + + +Change directory into the `shimatta-kenkyusho` folder cloned by git. + +Copy the `example.env` file to `.env` and edit it according to your needs: + +The following settings are required to be adapted: +- `DJANGO_STATIC_VOL`: The directory the application will extract its static data into, which needs to be served by your webserver. See the example reverse proxy setup for more details. +- `DJANGO_MEDIA_VOL`: The directory all media files like images uploaded to the application are stored here. This folder must be served by your webserver on the configured media URL. +- `PGDATA_VOL`: The directory, the postgres database will store its files. +- `PORT`: The TCP/IP port that the whole setup will listen on. Use a reverse proxy to forward to this port. Do not directly expose it to the internet! +- `DJANGO_SECRET_KEY`: Provide a secret, and randomly generated key. Do not share this with anybody! +- `DJANGO_ALLOWED_HOST`: Set this to the domain, the application will be reached at. E.g: `lab.example.com` +- `DJANGO_MEDIA_URL`: Set this to the media URL at which your webserver serves the `DJANGO_MEDIA_VOL` diretory. E.g: `media.lab.example.com/` Note the **slash at the end**. It is important. + +Once the environment is set up, the docker containers can be built and started. Run +``` +$ docker compose build +``` +This will generate two container images: +1. `shimatta-kenkyusho-shimatta-kenkyusho-web`: The django application +2. `postgres`: A alpine based docker container containing the postgres database. + +Start the application as a service with +``` +$ docker compose up -d +``` +> Note: The initial startup might need a minute because the whole database etc needs to be initialized first. + +Use +``` +$ docker ps +``` +to check if the `shimatta-kenkyusho-shimatta-kenkyusho-db` and the `shimatta-kenkyusho-shimatta-kenkyusho-web` container are running and report a *healthy status*. + +### Setup Initial Login User +> TODO + + +### Example Reverse Proxy Setup Using nginx +Once the setup is configured the reverse proxy setup is needed. This setup serves three purposes: +1. Redirect incoming requests to the django application running on the port `PORT` configured in the `.env` +2. Serve static files ath the URL: (e.g. `lab.example.com/static`). See `ALLOWED_HOST` configuration. +3. Serve the media volume at the media URL (e.g. `media.lab.example.com`). See `DJANGO_MEDIA_URL` + +Example nginx configuration for `nginx >v2.25` with SSL and http2 / http3 support: +``` +# Force redirection from http to https for application +server { + listen 80; + listen [::]:80; + server_name lab.example.com; # This must match your ALLOWED_HOST. Adapt domain. + allow all; + + return 301 https://lab.example.com$request_uri; # Adapt domain +} + +# Force redirection from http to https for media url +server { + listen 80; + listen [::]:80; + server_name media.lab.example.com; # Adapt domain name according to DJANGO_MEDIA_URL + allow all; + return 301 https://media.lab.example.com$request_uri; # Adapt domain name +} + +# Reverse Proxy for application +server { + listen 443 ssl; + listen [::]:443 ssl; + http2 on; + + + # Add this for HTTP3. If your nginx is older than 2.25 this might not be available +###################################################################################### + # listen 443 quic reuseport; + # listen [::]:443 quic reuseport; + # Enable QUIC and HTTP/3 + # ssl_early_data on; + # add_header Alt-Svc 'h3=":443"; ma=86400'; +####################################################################################### + + server_name lab.example.com; # Adapt domain + + # Use letsencrypt as SSL certificate provider. + ssl_certificate /etc/letsencrypt/live/lab.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/lab.example.com/privkey.pem; + + ssl_protocols TLSv1.3; + ssl_prefer_server_ciphers on; + + ssl_session_cache shared:SSL:1m; + ssl_session_timeout 5m; + + ssl_ciphers HIGH:!aNULL:!MD5; + + location / { + allow all; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_pass http://127.0.0.1:8000; # Adapt PORT from .env + } + + location /static/ { + # Adapt path to static volume here. Note the slash at the end + alias /path/to/DJANGO_STATIC_VOL/; + allow all; + } + + client_max_body_size 60m; + +} + +# Serve the media files +server { + listen 443 ssl; + listen [::]:443 ssl; + # Add this for HTTP3. If your nginx is older than 2.25 this might not be available +###################################################################################### + # listen 443 quic reuseport; + # listen [::]:443 quic reuseport; + # Enable QUIC and HTTP/3 + # ssl_early_data on; + # add_header Alt-Svc 'h3=":443"; ma=86400'; +####################################################################################### + http2 on; + + server_name media.lab.example.com; # Adapt according to DJANGO_MEDIA_URL + + # Use letsencrypt as SSL certificate provider. + ssl_certificate /etc/letsencrypt/live/media.lab.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/media.lab.example.com/privkey.pem; + + ssl_protocols TLSv1.3; + ssl_prefer_server_ciphers on; + + ssl_session_cache shared:SSL:1m; + ssl_session_timeout 5m; + + ssl_ciphers HIGH:!aNULL:!MD5; + error_page 502 /lab_down.html; + + allow all; + root /path/to /DJANGO_MEDIA_VOL/; # Adapt this to the volume provided. +} +``` +Congratulations. Your shimatta kenkyusho installation is now fully setup. +> Note that, the `compose.yaml` contains a restart-policy. By default the contianers will restart automatically, even after a reboot of the host machine, if the docker service is enabled. + + +## Backup and Restore +> TODO + +## Debugging and Development +> Todo + diff --git a/.env.example b/example.env similarity index 100% rename from .env.example rename to example.env From 4ff71d2b216f8ba1e1d232d5f96804b2bbbd66b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Sat, 23 Nov 2024 01:13:19 +0100 Subject: [PATCH 3/9] Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 62ce03e..23b50e4 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Clone this repository: $ git clone https://git.shimatta.de/mhu/shimatta-kenkyusho.git ``` -> Note: Shimatta Kenkyusho is currently not stable yet and the newest verison is in the `develop` branch. This will change once actual releases are done and merged to the `master` branch. You will be alble to get the latest stable version from the `master` branch or a repsective tag. For now, the `develop` is recommended. +> Note: Shimatta Kenkyusho is currently not stable yet and the newest verison is in the `develop` branch. This will change once actual releases are done and merged to the `master` branch. You will be able to get the latest stable version from the `master` branch or a repsective tag. For now, the `develop` is recommended. Change directory into the `shimatta-kenkyusho` folder cloned by git. From 2fdcfe8baf4f026a8a228f4b5db62ed497c7df79 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Sat, 23 Nov 2024 22:03:19 +0100 Subject: [PATCH 4/9] write docu about user setup --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 23b50e4..2d28688 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,9 @@ $ docker ps to check if the `shimatta-kenkyusho-shimatta-kenkyusho-db` and the `shimatta-kenkyusho-shimatta-kenkyusho-web` container are running and report a *healthy status*. ### Setup Initial Login User -> TODO +When started the for the first time with a fresh database without any superuser configured, a superuser `admin` with password `admin` will be automatically generated. +Use this user to login for the first time. In the django admin panel you can then either change the password of the `admin` user or create a new superuser with your own username and delete the `admin` user. +As long as there is at least one superuser configured, no admin user will be regenerated upon startup. ### Example Reverse Proxy Setup Using nginx From 146c2da4f3b35fb19b7a3def47bc91080a61892c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Mon, 25 Nov 2024 23:38:37 +0100 Subject: [PATCH 5/9] Make the container run as root by default, if env variables are missing, to be backwards compatible to old setup --- compose.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/compose.yaml b/compose.yaml index 4d19477..699f024 100644 --- a/compose.yaml +++ b/compose.yaml @@ -5,7 +5,7 @@ services: shimatta-kenkyusho-web: <<: *restart_policy build: . - user: "${DJANGO_USER_ID}:${DJANGO_USER_GID}" + user: "${DJANGO_USER_ID:-0}:${DJANGO_USER_GID:-0}" volumes: - "${DJANGO_STATIC_VOL:-./run/static}:/var/static" - "${DJANGO_MEDIA_VOL:-./run/media}:/var/media" From cfb9970c26e488da1304e6496d58daf1501814ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Mon, 25 Nov 2024 23:39:15 +0100 Subject: [PATCH 6/9] Add documentation. Debugging and porting still missing. Initial setup explained --- README.md | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 2d28688..65a4db5 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,10 @@ The following settings are required to be adapted: - `DJANGO_SECRET_KEY`: Provide a secret, and randomly generated key. Do not share this with anybody! - `DJANGO_ALLOWED_HOST`: Set this to the domain, the application will be reached at. E.g: `lab.example.com` - `DJANGO_MEDIA_URL`: Set this to the media URL at which your webserver serves the `DJANGO_MEDIA_VOL` diretory. E.g: `media.lab.example.com/` Note the **slash at the end**. It is important. +- `DJANGO_USER_ID`: The user ID to run the application inside the docker container. This is the user id, that is used to write the to `DJANGO_STATIC_VOL` and `DJANGO_MEDIA_VOL`. Make sure the user has access. +- `DJANGO_USER_GID`: The group ID to run the application inside the docker container. This is the group id, that is used to write the to `DJANGO_STATIC_VOL` and `DJANGO_MEDIA_VOL`. + +> Note: It is not recommended to run the docker container without a set `DJANGO_USER_ID` and `DJANGO_USER_GID`. It will default to `0 (root)`. Once the environment is set up, the docker containers can be built and started. Run ``` @@ -96,18 +100,18 @@ server { # Reverse Proxy for application server { - listen 443 ssl; - listen [::]:443 ssl; - http2 on; + listen 443 ssl; + listen [::]:443 ssl; + http2 on; # Add this for HTTP3. If your nginx is older than 2.25 this might not be available ###################################################################################### - # listen 443 quic reuseport; - # listen [::]:443 quic reuseport; - # Enable QUIC and HTTP/3 - # ssl_early_data on; - # add_header Alt-Svc 'h3=":443"; ma=86400'; + # listen 443 quic reuseport; + # listen [::]:443 quic reuseport; + # Enable QUIC and HTTP/3 + # ssl_early_data on; + # add_header Alt-Svc 'h3=":443"; ma=86400'; ####################################################################################### server_name lab.example.com; # Adapt domain @@ -146,7 +150,7 @@ server { server { listen 443 ssl; listen [::]:443 ssl; - # Add this for HTTP3. If your nginx is older than 2.25 this might not be available + # Add this for HTTP3. If your nginx is older than 2.25 this might not be available ###################################################################################### # listen 443 quic reuseport; # listen [::]:443 quic reuseport; @@ -158,15 +162,15 @@ server { server_name media.lab.example.com; # Adapt according to DJANGO_MEDIA_URL - # Use letsencrypt as SSL certificate provider. - ssl_certificate /etc/letsencrypt/live/media.lab.example.com/fullchain.pem; - ssl_certificate_key /etc/letsencrypt/live/media.lab.example.com/privkey.pem; + # Use letsencrypt as SSL certificate provider. + ssl_certificate /etc/letsencrypt/live/media.lab.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/media.lab.example.com/privkey.pem; - ssl_protocols TLSv1.3; - ssl_prefer_server_ciphers on; + ssl_protocols TLSv1.3; + ssl_prefer_server_ciphers on; - ssl_session_cache shared:SSL:1m; - ssl_session_timeout 5m; + ssl_session_cache shared:SSL:1m; + ssl_ession_timeout 5m; ssl_ciphers HIGH:!aNULL:!MD5; error_page 502 /lab_down.html; From befd5e452f0d438ce6a722cf573aee94a758b9c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Mon, 25 Nov 2024 23:48:49 +0100 Subject: [PATCH 7/9] Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 65a4db5..a24c0f3 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Clone this repository: $ git clone https://git.shimatta.de/mhu/shimatta-kenkyusho.git ``` -> Note: Shimatta Kenkyusho is currently not stable yet and the newest verison is in the `develop` branch. This will change once actual releases are done and merged to the `master` branch. You will be able to get the latest stable version from the `master` branch or a repsective tag. For now, the `develop` is recommended. +> Note: Shimatta Kenkyusho is currently not stable yet and the newest verison is in the `develop` branch. This will change once actual releases are done and merged to the `master` branch. You will be able to get the latest stable version from the `master` branch or a respective tag. For now, the `develop` is recommended. Change directory into the `shimatta-kenkyusho` folder cloned by git. From 0b26a81b9445d8c339eac65394400c2d96e4b2ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Mon, 25 Nov 2024 23:50:41 +0100 Subject: [PATCH 8/9] Add disclaimer --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index a24c0f3..f73898c 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,7 @@ Once the setup is configured the reverse proxy setup is needed. This setup serve 3. Serve the media volume at the media URL (e.g. `media.lab.example.com`). See `DJANGO_MEDIA_URL` Example nginx configuration for `nginx >v2.25` with SSL and http2 / http3 support: +> Note: This is by no means a replacement for the documentation of nginx and only serves as an example. Consult the documentation of your nginx version reagrding security and other issues. ``` # Force redirection from http to https for application server { From 19852dd5add870be395499285726c41e6c3e5df7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Mon, 27 Jan 2025 19:26:31 +0100 Subject: [PATCH 9/9] Fix issues from PR #27. Ready to be merged. --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index f73898c..378f9b8 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ ## Installation ### Prerequisites -Shimatta Kenkyusho (しまった・研究所) is a Django based web application. It is highly recommended to run it using the supplied docker setup. This removes the need of any special installation on the host system. This guide assumes, that `nginx` is running on the host system and can serve as a reverse proxy and webserver. For easiest download, it is recommended to clone the desired release with `git` +Shimatta Kenkyusho (しまった・研究所) is a Django based web application. It is highly recommended to run it using the supplied docker setup. This removes the need of any special installation on the host system. This guide assumes, that `nginx` is running on the host system and can serve as a reverse proxy and webserver. For easiest download, it is recommended to clone the desired release with `git`. Install the requirements: @@ -36,7 +36,7 @@ The following settings are required to be adapted: - `DJANGO_STATIC_VOL`: The directory the application will extract its static data into, which needs to be served by your webserver. See the example reverse proxy setup for more details. - `DJANGO_MEDIA_VOL`: The directory all media files like images uploaded to the application are stored here. This folder must be served by your webserver on the configured media URL. - `PGDATA_VOL`: The directory, the postgres database will store its files. -- `PORT`: The TCP/IP port that the whole setup will listen on. Use a reverse proxy to forward to this port. Do not directly expose it to the internet! +- `PORT`: The TCP/IP port that the whole setup will listen on. Use a reverse proxy to forward to this port. *Do not directly expose it to the internet!* - `DJANGO_SECRET_KEY`: Provide a secret, and randomly generated key. Do not share this with anybody! - `DJANGO_ALLOWED_HOST`: Set this to the domain, the application will be reached at. E.g: `lab.example.com` - `DJANGO_MEDIA_URL`: Set this to the media URL at which your webserver serves the `DJANGO_MEDIA_VOL` diretory. E.g: `media.lab.example.com/` Note the **slash at the end**. It is important. @@ -57,7 +57,7 @@ Start the application as a service with ``` $ docker compose up -d ``` -> Note: The initial startup might need a minute because the whole database etc needs to be initialized first. +> Note: The initial startup might need a minute because the whole database etc. needs to be initialized first. Use ``` @@ -66,7 +66,7 @@ $ docker ps to check if the `shimatta-kenkyusho-shimatta-kenkyusho-db` and the `shimatta-kenkyusho-shimatta-kenkyusho-web` container are running and report a *healthy status*. ### Setup Initial Login User -When started the for the first time with a fresh database without any superuser configured, a superuser `admin` with password `admin` will be automatically generated. +When started for the first time with a fresh database without any superuser configured, a superuser `admin` with password `admin` will be automatically generated. Use this user to login for the first time. In the django admin panel you can then either change the password of the `admin` user or create a new superuser with your own username and delete the `admin` user. As long as there is at least one superuser configured, no admin user will be regenerated upon startup. @@ -74,7 +74,7 @@ As long as there is at least one superuser configured, no admin user will be reg ### Example Reverse Proxy Setup Using nginx Once the setup is configured the reverse proxy setup is needed. This setup serves three purposes: 1. Redirect incoming requests to the django application running on the port `PORT` configured in the `.env` -2. Serve static files ath the URL: (e.g. `lab.example.com/static`). See `ALLOWED_HOST` configuration. +2. Serve static files at the URL: (e.g. `lab.example.com/static`). See `ALLOWED_HOST` configuration. 3. Serve the media volume at the media URL (e.g. `media.lab.example.com`). See `DJANGO_MEDIA_URL` Example nginx configuration for `nginx >v2.25` with SSL and http2 / http3 support: