Skip to content
Colibri Social Documentation

Overview

This section is the practical counterpart to the architecture pages: how to get Colibri running on your own machine and what to expect once it is. If you want to run an instance for other people rather than hack on one, read Self-Hosting instead.

What you’re going to run

Section titled “What you’re going to run”

Colibri is split across two repositories, and local development normally involves both:

Repository Contains Runs as
colibri-social/appview The AppView (Rust/Rocket), its migrations, and the compose files for its dependencies cargo run on 127.0.0.1:8000
colibri-social/colibri.social The client library, the website that hosts it, the native shell, and this documentation pnpm dev:client on 127.0.0.1:4321

Around the AppView sit a handful of containers, all from docker-compose.dev.yml and docker-compose.pds.dev.yml in the AppView repository:

  • PostgreSQL, shared by the AppView and Tap.
  • Tap, the firehose consumer that backfills repositories and streams live records to the AppView.
  • A PDS, which hosts the repository of every community you create, plus a small private PLC directory so the DIDs it mints stay local. Both come from docker-compose.pds.dev.yml, see Running a PDS.

Your own account is not part of the local stack. You log in with a real Atmosphere account on a real PDS (bsky.social or wherever your account lives), and only community repositories live on the PDS you configure.

Prerequisites

Section titled “Prerequisites”
  • Linux, ideally. The AppView is only tested there, and its voice SFU (mediasoup) does not build on Windows. macOS works for most day-to-day work.
  • Rust 1.96+ (rust-toolchain.toml pins it, so rustup picks it up automatically).
  • Node.js ^24.13.0 and pnpm 10.33.0: run corepack enable and the right pnpm is used for you.
  • Docker and Docker Compose.
  • An Atmosphere account whose DID is in the client’s early-access allowlist (see Client development).

The short path

Section titled “The short path”

  1. Start the AppView’s dependencies and run it:

    Terminal window
    git clone https://github.com/colibri-social/appview.git
    cd appview
    cp .env.example .env
    # fill in .env, then:
    docker compose -f docker-compose.dev.yml -f docker-compose.pds.dev.yml up -d
    cargo run

    The second compose file adds a local PDS and PLC directory. Drop it if you don’t need to create communities.

  2. In a second checkout, start the client:

    Terminal window
    git clone https://github.com/colibri-social/colibri.social.git
    cd colibri.social
    pnpm install
    cp .env.example .env
    pnpm dev:client

  3. Open http://127.0.0.1:4321 (not localhost, see below) and log in with your Atmosphere account.

That gives you a working client against a local AppView, communities included. Set PDS_LOC=http://localhost:3000 and APPVIEW_HANDLE_DOMAIN=test in .env and the local PDS handles the rest. Running a PDS explains how that works and where its limits are.

Dev mode is not production

Section titled “Dev mode is not production”

The client takes several shortcuts when Vite is in dev mode. They are worth knowing, because they change how requests flow and they hide a few classes of bug until you build for production:

  • Requests bypass your PDS. In production every XRPC call is proxied through the user’s PDS with an atproto-proxy header, and the PDS mints the service-auth token. In dev the client calls http://localhost:8000/xrpc/... directly and mints the service-auth token itself with com.atproto.server.getServiceAuth. Proxy-only breakage therefore doesn’t show up locally.
  • The AppView origin is pinned. getAppViewHost() returns 127.0.0.1:8000 whenever import.meta.env.DEV is set, so the AppView switcher in settings has no effect locally.
  • The OAuth client is a localhost client. Per the AT Protocol localhost client rules, the client id is http://localhost?... with a redirect_uri of http://127.0.0.1:<port>/app/login. That redirect URI is why you must browse to 127.0.0.1, not localhost.
  • Early access is still enforced. The allowlist in packages/client/src/atproto/allowlist.ts is compiled into the client, in dev too.

Where to go next

Section titled “Where to go next”
AppView developmentRunning the Rust service, its dependencies, migrations, and tests.
Client developmentThe SolidJS client, the Astro website, and the native shell.
Running a PDSThe PDS communities live on, and how to run one locally.
ContributingChangesets, reviews, and how to get your work merged.