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: ```console user@host:~$ git clone https://github.com/rr-/szurubooru.git szuru user@host:~$ cd szuru ``` 2. Configure the application: ```console 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: ```console 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: ```console 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**](#Building) instead, then read here once you're done. 5. Run it! For first run, it is recommended to start the database separately: ```console user@host:szuru$ docker-compose up -d sql ``` To start all containers: ```console user@host:szuru$ docker-compose up -d ``` To view/monitor the application logs: ```console 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: ```diff yaml ... 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: ```console 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: ```console 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: ```console 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:///`. For an NGINX reverse proxy, that will appear as: ```nginx location /szuru { proxy_http_version 1.1; proxy_pass http:///; 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: ```nginx # 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; } ```