Excalifork

Welcome to excalifork!

Overview

This repository collects forks of the very well known Excalidraw. Main objective of excalifork is to have a fast way to deploy Excalidraw with collaboration features enabled, fully self-hosted.

Excalifork does not build any image itself: it just deploys pinned, pre-built images from actively maintained community forks that already implement a self-hostable storage/collaboration backend, wired together via ansible:

- https://hub.docker.com/r/alswl/excalidraw (frontend, `fork` branch)
- https://github.com/rizlas/excalidraw-storage-backend (storage backend)
- https://github.com/alswl/excalidraw-room-go (collaboration room server)

The exact image and tag for each of the three is pinned in ansible/group_vars/all/vars.yml.

The idea of a pluggable HTTP storage backend (instead of Firebase) originally comes from https://gitlab.com/kiliandeca/excalidraw-fork, which is no longer maintained. Excalifork (this repo) used to carry its own patch replicating that approach on top of a specific, known upstream Excalidraw tag. We no longer maintain that patch: we consume alswl/excalidraw:fork instead, whose tags (e.g. v0.18.1-fork-b2) name the upstream Excalidraw version they're built on.

The storage backend and room server are a different story: they're implementations only loosely related to any upstream. The storage backend is rizlas/excalidraw-storage-backend, a fork of kitsteam/excalidraw-storage-backend (itself descended from the same kiliandeca lineage) that restores support for every backend Keyv officially ships an adapter for (postgres, mysql, redis, valkey, mongo, sqlite, etcd, memcache, dynamo) via DATABASE_ADAPTER, which kitsteam's own version had silently narrowed down to postgres-only despite still documenting otherwise. This fix is proposed upstream in kitsteam/excalidraw-storage-backend#173; until (if) it's merged, excalifork runs the rizlas fork directly, with DATABASE_ADAPTER=redis. alswl/excalidraw-room-go is a from-scratch Go reimplementation of the official excalidraw/excalidraw-room protocol (itself unmaintained since 2023), not a fork of its code at all.

Following sections describe how to deploy excalifork using docker or kubernetes.

(The name: "Excali-" from Excalidraw, "-fork" because that's exactly what this repo is, a collection of forks wired together.)

Inventory setup

Both the docker and kubernetes deployments below are driven by ansible, and both read ansible/inventories/hosts.ini. It targets localhost out of the box, so it works as-is for a local/single-machine deployment. If you're deploying remotely instead (docker on a remote host over SSH), edit it in place or replace it with your own hosts and connection details; SSH access to the target is all that's required.

git clone https://github.com/rizlas/excalifork.git
cd excalifork/ansible

Then, copy group_vars/all/vault.yml.example to group_vars/all/vault.yml, fill in acme_email, domain and redis_password, and encrypt it:

cp group_vars/all/vault.yml.example group_vars/all/vault.yml
ansible-vault encrypt group_vars/all/vault.yml --vault-password-file ~/.vault.pwd

Every ansible-playbook command below needs --vault-password-file ~/.vault.pwd (or the equivalent --ask-vault-pass) to decrypt it.

Docker

Prerequisites

• Docker and ansible installed on your system
• A domain to issue SSL certificates
• Use uv sync to set up the Python environment (see pyproject.toml)

Usage

Run the Docker container:

ansible-playbook -i inventories/hosts.ini docker.yml --vault-password-file ~/.vault.pwd

Access Excalifork by opening your browser and navigating to your FQDN.

Don't want ansible at all? docker-compose.yml in the repo root is the same stack, plain: copy .env.example to .env, fill it in, then docker compose up -d.

Kubernetes

Prerequisites

• Kubernetes cluster configured
• kubectl installed

NOTE: In ansible/templates/kubernetes_resources.yml.j2 only based resources are provided. Further tuning of those should be done based on the cluster used, or other specifications, that cannot be known a priori (e.g. ingress controller, cert-manager...)

Deployment

1. Select cluster:

export KUBECONFIG=path_to_your_kubeconfig

2. Expose the service:

ansible-playbook -i inventories/hosts.ini kubernetes.yml --vault-password-file ~/.vault.pwd

Access Excalifork by opening your browser and navigating to your FQDN.

Proxy and TLS

TLS is highly suggested cause excalidraw use WSS protocol (do not use self signed certificates https://stackoverflow.com/questions/5312311/secure-websockets-with-self-signed-certificate). In docker-compose you'll find https://github.com/nginx-proxy/acme-companion.

Proxy is nginx with autobuild configuration thanks to https://github.com/nginx-proxy/nginx-proxy. Both images' versions are pinned as nginx_proxy_tag/acme_companion_tag in ansible/group_vars/all/vars.yml.

Contributing

Feel free to make pull requests, fork, destroy or whatever you like most. Any criticism is more than welcome.

License

This project is licensed under the MIT License.

#followtheturtle