CrazyWall

Self-Hostable, collaborative Detective Board

Features

• Invite others to your walls, collaborate in real time
• Draw connections using colored yarn, with arrows and descriptions
• Add images, links and tags to notes
• Gather info across multiple Boards

Self-hosting

The easiest way to host CrazyWall for yourself is to create a Docker Compose with the setup script:

bash <(curl -so- https://raw.githubusercontent.com/MaSp005/crazywall/refs/heads/main/deploy/make-compose.sh)
# Of course, always check the scripts you're piping into bash

If you don't fancy running a script, you can also use the template:

curl -o docker-compose.yml https://raw.githubusercontent.com/MaSp005/crazywall/refs/heads/main/deploy/docker-compose.yml.template
nano docker-compose.yml # or whatever your favourite editor is

Warning

Using S3 as storage for walls is not tested and may be unstable or unusable.

Note

In production, you'll probably want to expose the two backend ports through a reverse proxy like Caddy or nginx. The setup script provides you with an exemplary config for those two. For template users: The network proxy_network is intended as the external network that your existing proxy container lives in, so you can simply point your desired hosts to crazywall:1234 and crazywall:3000.

Start the entire stack with:

docker compose up -d

To understand how to set up your proxy and the services' environment variables to ensure connectivity, see this diagram:

Development

CrazyWall requires a Postgres Database and a static file server or reverse proxy for serving files. These are set up for development in docker-compose.yml.dev-template, along with adminer for quick database inspection.

To get started for development:

0. Required tools: Docker, Git, Bun
1. Clone this repository.
2. Set up docker-compose.yml.dev-template:
   • Fill in services.backend.environment.DISCORD_APPID and DISCORD_SECRET. Generate at Discord Developer Portal.
     • Other placeholders are fine to keep for local development.
   • Rename to docker-compose.yml.
3. Run docker compose watch crazywall.

The backend application runs on Bun and uses Bun.serve to serve both the frontend and API. The same container hosts the central Y.js server using Hocuspocus. It uses BetterAuth for authentication, allowing easy expansion. The frontend uses Valtio for State Management, plugging into the Y.js CRDT using Valtio-Yjs.

Database Migrations

This project uses DBMate for automatic migration of the database. If your additions require changing the database schema, create a new migration:

Add a volume to the service:

services:
  crazywall:
    # ...
    volumes:
      - ./migrations:/home/bun/app/migrations

then run

docker compose up --force-recreate crazywall
docker compose exec crazywall dbmate -e DB_CONNECTION_STRING --wait -d ./migrations n [[DESCRIPTION]]
# Files from docker volumes are owned by root:root by default, change owner:
sudo chown $USER:$USER ./migrations/*

This will create a new file in ./migrations, which you can populate with your desired changes to the schema. (be sure to enter the downgrades as well). To apply the new migration, restart the crazywall container or run

docker compose exec crazywall dbmate -e DB_CONNECTION_STRING --wait -d ./migrations up
# OR
docker compose restart crazywall

BetterAuth Migrations

When changing the BetterAuth configuration in a way that requires migrating the database, @better-auth/cli gets difficult, so here's some guidance:

• ⚠️ Running in the crazywall container fails when installing the dependency, since it needs to compile better-sqlite3 (even though it is not used), the tools for which are not installed in the container.
• Copy the environment variables DB_CONNECTION_STRING, DISCORD_APPID and DISCORD_SECRET (or NO_LOGIN) from the backend service and reformat them to be shell-compliant, replace postgres with localhost:5432.
• Export the variables in your shell, then run bunx @better-auth/cli migrate. Chances are Bun will take forever resolving dependencies, in that case you can use npx @better-auth/cli migrate instead.

If you intend on doing this a lot, it'd be preferable to put your environment variables in a .env instead and reference that from your compose.

The BetterAuth CLI creates new migrations in its own directory better-auth_migrations. Add the new changes to the upgrade section of a new native migration, created as explained above. BetterAuth does not, however, generate the respective revert script. You'll have to do that yourself.