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 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.

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.
• 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

$ 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

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

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:

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 {
        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_ession_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