INSTALL.md

This assumes that you have Docker (version 17.05 or greater) and Docker Compose (version 1.6.0 or greater) already installed.

Prepare things

1. Download the szurubooru source:

   user@host:~$ git clone https://github.com/rr-/szurubooru.git szuru
   user@host:~$ cd szuru

2. Configure the application:

   user@host:szuru$ cp server/config.yaml.dist server/config.yaml
   user@host:szuru$ edit server/config.yaml

   Pay extra attention to these fields:

   • secret
   • the smtp section.

   You can omit lines when you want to use the defaults of that field.

3. Configure Docker Compose:

   user@host:szuru$ cp doc/example.env .env
   user@host:szuru$ edit .env

   Change the values of the variables in .env as needed. Read the comments to guide you. Note that .env should be in the root directory of this repository.

4. Pull the containers:

   This pulls the latest containers from docker.io:

   user@host:szuru$ docker-compose pull

   If you have modified the application's source and would like to manually build it, follow the instructions in Building instead, then read here once you're done.

5. Run it!

   For first run, it is recommended to start the database separately:

   user@host:szuru$ docker-compose up -d sql

   To start all containers:

   user@host:szuru$ docker-compose up -d

   To view/monitor the application logs:

   user@host:szuru$ docker-compose logs -f
   # (CTRL+C to exit)

Building

1. Edit docker-compose.yml to tell Docker to build instead of pull containers:

   ...
   server:
   - image: szurubooru/server:latest
   + build: server
   ...
   client:
   - image: szurubooru/client:latest
   + build: client
   ...

   You can choose to build either one from source.

2. Build the containers:

   user@host:szuru$ docker-compose build

   That will attempt to build both containers, but you can specify client or server to make it build only one.

   If docker-compose build spits out:

   ERROR: Service 'server' failed to build: failed to parse platform : "" is an invalid component of "": platform specifier component must match "^[A-Za-z0-9_-]+$": invalid argument
   

   ...you will need to export Docker BuildKit flags:

   user@host:szuru$ export DOCKER_BUILDKIT=1; export COMPOSE_DOCKER_CLI_BUILD=1

   ...and run docker-compose build again.

Note: If your changes are not taking effect in your builds, consider building with --no-cache.

Additional Features

1. CLI-level administrative tools

   You can use the included szuru-admin script to perform various administrative tasks such as changing or resetting a user password. To run from docker:

   user@host:szuru$ docker-compose run server ./szuru-admin --help

   will give you a breakdown on all available commands.

2. Using a seperate domain to host static files (image content)

   If you want to host your website on, (http://example.com/) but want to serve the images on a different domain, (http://static.example.com/) then you can run the backend container with an additional environment variable DATA_URL=http://static.example.com/. Make sure that this additional host has access contents to the /data volume mounted in the backend.

3. Setting a specific base URI for proxying

   Some users may wish to access the service at a different base URI, such as http://example.com/szuru/, commonly when sharing multiple HTTP services on one domain using a reverse proxy. In this case, simply set BASE_URL="/szuru/" in your .env file.

   Note that this will require a reverse proxy to function. You should set your reverse proxy to proxy http(s)://example.com/szuru to http://<internal IP or hostname of frontend container>/. For an NGINX reverse proxy, that will appear as:

   location /szuru {
       proxy_http_version 1.1;
       proxy_pass http://<internal IP or hostname of frontend container>/;
   
       proxy_set_header Host              $http_host;
       proxy_set_header Upgrade           $http_upgrade;
       proxy_set_header Connection        "upgrade";
       proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
       proxy_set_header X-Scheme          $scheme;
       proxy_set_header X-Real-IP         $remote_addr;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Script-Name     /szuru;
   }

4. Preparing for production

   If you plan on using szurubooru in a production setting, you may opt to use a reverse proxy for added security and caching capabilities. Start by having the client docker listen only on localhost by changing PORT in your .env file to 127.0.0.1:8080 instead of simply :8080. Then configure NGINX (or your caching/reverse proxy server of your choice) to proxy_pass http://127.0.0.1:8080. An example config is shown below:

   # ideally, use ssl termination + cdn with a provider such as cloudflare.
   # modify as needed!
   
   # rate limiting zone
   # poor man's ddos protection, essentially
   limit_req_zone $binary_remote_addr zone=throttle:10m rate=25r/s;
   
   # www -> non-www
   server {
     listen 80;
     listen [::]:80;
     server_tokens off;
     server_name www.example.com
     return 301 http://example.com$request_uri;
   }
   
   server {
     server_name example.com;
     client_max_body_size 100M;
     client_body_timeout 30s;
     server_tokens off;
     location / {
       limit_req zone=throttle burst=5 delay=3;
       proxy_http_version 1.1;
       proxy_pass http://127.0.0.1:8080;
       proxy_set_header Host $http_host;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Scheme $scheme;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Script-Name /szuru;
       error_page 500 501 502 504 505 506 507 508 509 510 511 @err;
       error_page 503 @throttle;
     }
   
     location @err {
       return 500 "server error. please try again later.";
       default_type text/plain;
     }
     location @throttle {
       return 503 "we've detected abuse on your ip. please wait and try again later.";
       default_type text/plain;
     }
     listen 80;
     listen [::]:80;
   }