running-with-docker.md

title	summary	sidebar_position
Running with Docker	A comprehensive guide on how to set up chibisafe with Docker	1

Running chibisafe with Docker

This document will guide you in setting up chibisafe with Docker. Although it's not the only method, it is the preferred way to run the service given its ease of use.

The fastest and easiest method to run chibisafe nowdays is by using the official Docker images we provide. This lets you get up and running with only a few commands and it comes in 2 different flavors:

• The stable version, usually with the tag :latest
• And the development version which is a build based on the current master branch. You can access this one with the :dev tag

:::tip Keep in mind you need Docker installed to continue with this guide. If you don't then you can follow the install instructions on their website. :::

Configuring

In order to use our images you need to create somewhere in your system just 2 files, docker-compose.yml and Caddyfile. The way our docker compose file is structured it will create 3 services which are the chibisafe backend, the chibisafe frontend, and a very minimal caddy instance to merge those 2 services into 1 resulting port.

This is what your directory should look like

└── chibisafe
    ├── docker-compose.yml
    └── Caddyfile

services:
  chibisafe:
    image: chibisafe/chibisafe:latest
    environment:
      - BASE_API_URL=http://chibisafe_server:8000
    expose:
      - 8001
    restart: unless-stopped

  chibisafe_server:
    image: chibisafe/chibisafe-server:latest
    volumes:
      - ./database:/app/database:rw
      - ./uploads:/app/uploads:rw
      - ./logs:/app/logs:rw
    expose:
      - 8000
    restart: unless-stopped

  caddy:
    image: caddy:2-alpine
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./uploads:/app/uploads:ro
    ports:
      - 24424:80
    environment:
      - BASE_URL=":80"
    restart: unless-stopped

:::danger Even if you use NGINX Proxy Manager, or Caddy in your host system, it is still necessary to have Caddy inside the docker compose file. Do not change these options unless you know what you are doing, otherwise you'll break the routing. :::

Now that your docker-compose.yml file is set up it's now time to create the Caddyfile to finish the configuration process:

{$BASE_URL} {
	route {
		file_server * {
				root /app/uploads
				pass_thru
		}

		@api path /api/*
		reverse_proxy @api http://chibisafe_server:8000 {
				header_up Host {http.reverse_proxy.upstream.hostport}
				header_up X-Real-IP {http.request.header.X-Real-IP}
		}

		@docs path /docs*
		reverse_proxy @docs http://chibisafe_server:8000 {
				header_up Host {http.reverse_proxy.upstream.hostport}
				header_up X-Real-IP {http.request.header.X-Real-IP}
		}

		reverse_proxy http://chibisafe:8001 {
				header_up Host {http.reverse_proxy.upstream.hostport}
				header_up X-Real-IP {http.request.header.X-Real-IP}
		}
	}
}

Running chibisafe

Now that you have every piece needed, you can launch chibisafe by running the following command:

docker compose up

:::tip If you want to run it detached so that you can close your terminal but chibisafe continues running, run docker compose up -d instead. :::

After the chibisafe images are pulled and the setup process finishes, you will be able to access your new chibisafe instance by going to localhost:24424 on your browser.

:::danger The default credentials for a new chibisafe installation for both username and password are admin so be sure to change them! :::

Reverse proxy

In order to attach a domain name to an application running with an exposed port like chibisafe you need to set up a reverse proxy in your system. The 2 most common solutions for this are Caddy and NGINX, and we prefer Caddy since it's simpler to use and understand. For that reason we'll only be providing a Caddyfile configuration snippet to get you up and running, so if you have further questions you can head to our Discord support server and ask or open a GitHub issue and we'll try to get back to you as soon as possible.

Caddy

:::tip This section explains configuration options for Caddy installs on your host system. This is separate from the Caddy install used within the Chibisafe stack. :::

Once you have Caddy installed locally you can add this to your Caddyfile in order reverse proxy the exposed port from chibisafe:

your-chibisafe-domain.com {
	reverse_proxy localhost:24424
}

If you use Cloudflare or a similar service and want your instance to be proxied by them, you should instead use the one below since it adds the necessary headers to pass the visitor's IP to the chibisafe instance. Note that the trusted proxies and X-Forwarded-For headers are specifically made for use with Cloudflare and will require modification for other proxies.

your-chibisafe-domain.com {
	tls internal
	reverse_proxy localhost:24424 {
		trusted_proxies 173.245.48.0/20 103.21.244.0/22 103.22.200.0/22 103.31.4.0/22 141.101.64.0/18 108.162.192.0/18 190.93.240.0/20 188.114.96.0/20 197.234.240.0/22 198.41.128.0/17 162.158.0.0/15 104.16.0.0/13 104.24.0.0/14 172.64.0.0/13 131.0.72.0/22 2400:cb00::/32 2606:4700::/32 2803:f800::/32 2405:b500::/32 2405:8100::/32 2a06:98c0::/29 2c0f:f248::/32
		header_up X-Forwarded-For {http.request.header.CF-Connecting-IP}
	}
}

After correctly setting your Caddyfile and restarting the caddy process in your system, you should be able to visit your instance with the domain name and start using it.

Nginx

Configuring Nginx is more difficult so we're only providing with a skeleton config for you to modify and add https to it with certbot or by supplying your own keys

# for reference purposes only
# Chibisafe Reverse Proxy

server {
	server_name chibi.domain;
	listen [::]:443 ssl;
	listen 443 ssl;

	location / {
		proxy_pass http://localhost:24424/;
		proxy_set_header Host $host;
		proxy_set_header X-Forwarded-Host $host;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	}

	# Settings managed by certbot
	ssl_certificate /etc/letsencrypt/live/your.domain.com/fullchain.pem;
	ssl_certificate_key /etc/letsencrypt/live/your.domain.com/privkey.pem;
	include /etc/letsencrypt/options-ssl-nginx.conf;
	ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}

:::tip Make sure to change chibi.domain for your own domain name. :::

Next steps

Now that everything is up and running, if you want to update chibisafe to a new version once a new release is available you can run the following command to do so:

docker compose pull && docker compose up -d

This will pull the latest version available and restart your service automatically.