From source

This guide runs HappyView directly with cargo run, from a clone of its alpha branch. If you’d rather run the whole stack in containers, see Running the development stack in HappyView’s CONTRIBUTING.md. To deploy from prebuilt images, see Docker.

Prerequisites

• rustup. The repository’s rust-toolchain.toml pins the Rust version, and rustup installs it on the first build.
• Node.js and npm, to build the dashboard.
• (Optional) PostgreSQL if you prefer Postgres over the default SQLite. The repository’s Compose files and tests use version 17.

1. Clone and configure

git clone --branch alpha https://github.com/gamesgamesgamesgamesgames/happyview
cd happyview
cp .env.example .env

The default branch holds v2, so name alpha. Edit .env to point at your running services:

# SQLite (the default): no setup needed, the file is created automatically
DATABASE_URL=sqlite://data/happyview.db?mode=rwc
PUBLIC_URL=http://127.0.0.1:3000
# Generate with: openssl rand -base64 48
SESSION_SECRET=

Use 127.0.0.1, not localhost

atproto OAuth loopback clients are registered with 127.0.0.1. If you set PUBLIC_URL to http://localhost:3000, OAuth sign-in will fail because the redirect URI won’t match the loopback client ID. Always use http://127.0.0.1:3000 for local development.

Or if you prefer Postgres:

DATABASE_URL=postgres://happyview:happyview@localhost/happyview

See Configuring an instance for what to set first, the Configuration reference for every variable, and the database setup guide for details on both backends.

2. Create the database (Postgres only)

If using SQLite, skip this step: HappyView creates the database file automatically.

If using Postgres:

createdb happyview

Or if using a Postgres user with a password:

psql -c "CREATE DATABASE happyview;" -U postgres

HappyView runs migrations automatically on startup, so no manual migration step is needed.

3. Build the dashboard

A plain cargo run carries no dashboard of its own and serves ./web/out, so export it once:

cd web
npm ci
npm run build
cd ..

Skip this if you need only the API. Run it again after pulling changes to web/.

4. Start HappyView

cargo run

HappyView starts on port 3000 (configurable via the PORT environment variable). curl http://127.0.0.1:3000/health answers ok once it’s listening.

Next steps

Your HappyView instance is running. Install an interpreter before saving any script: a self-hosted instance ships with none (Languages). Then deploy a project to it.