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

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

# chibisafe/docker-compose.yml
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

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

# chibisafe/Caddyfile
{$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

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.

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

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

# /etc/caddy/Caddyfile
your-chibisafe-domain.com {
	tls internal
	reverse_proxy localhost:24424
}

If you are a CloudFlare user 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.

# /etc/caddy/Caddyfile
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;
}

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.