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

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.


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.

version: "3.7"

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

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

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

Even if you use NGINX Proxy Manager, or Caddy in your host system, it is still necessary to hhave 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:

	route {
		file_server * {
				root /app/uploads

		@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

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.

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.


Once you have Caddy installed locally you can add this to your Caddyfile in order reverse proxy the exposed port from chibisafe: {
	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. {
	tls internal
	reverse_proxy localhost:24424 {
		trusted_proxies 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.


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/;
	ssl_certificate_key /etc/letsencrypt/live/;
	include /etc/letsencrypt/options-ssl-nginx.conf;
	ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

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.