Deploying

This page deploys your project to an instance: you sign in to it once with hpy, preview what a deploy would change, then deploy. The same steps work for an instance on HappyProto and one you run yourself.

Before you start

• Run your checks. hpy happyview check builds the project the way an instance will, and hpy happyview test runs your tests. Fix what they report first.
• An instance running HappyView v3. On HappyProto, your instance is part of your HappyProto project; HappyProto is in beta, by invite. To run your own, follow Self-hosting. An instance started with HAPPYVIEW_PROJECT serves that directory and refuses a deploy.
• An operator account on it with the project:deploy permission. On a self-hosted instance, the first account to sign in to its dashboard, or the one its SUPERADMIN_DID names, has every permission and can give other accounts permissions under Access > Users. The Manager template includes project:deploy.
• A PDS that supports atproto permission sets, a recent part of atproto OAuth that lets an app ask for a named bundle of permissions. Signing in asks your PDS to grant hpy HappyView’s admin permissions; a PDS that can’t is refused with a message saying so. To deploy without signing in, use an API key, as Deploy from CI does.

Sign in to the instance

HappyProto

Your instance’s URL is in your HappyProto project, in the HappyProto dashboard.

hpy happyview login --url https://<your instance>

Self-hosted

Use the instance’s public URL, the one its PUBLIC_URL names.

hpy happyview login --url https://happyview.example.com

hpy opens your browser to sign in with your atproto account, and remembers the session. hpy happyview whoami shows who you’re signed in as, and hpy happyview logout signs out.

If you’re signed in to more than one instance, pass --url to each command below to say which.

Preview the deploy

hpy happyview deploy --dry-run

A dry run builds your project on the instance and lists what would change, the plugins it would install, and any backfills it would start, without changing anything. If the project doesn’t build there, it lists the problems with their files and lines. While a plugin is still to be installed, the instance may not be able to build the project yet: the dry run says so, and the deploy builds it again after the plugins are in place.

Deploy

hpy happyview deploy

hpy shows the same preview and asks you to confirm (--yes skips the question). Then it:

1. installs the interpreters and libraries your happyview.lock names, at exactly those versions;
2. sends your project: happyview.toml, everything under src/, and each [modules] build;
3. starts the backfills your lexicons ask for.

The instance builds the project before it switches over. If the build fails, nothing changes: the project that was already there keeps serving, and the deploy prints the problems.

When it’s done, call your endpoint on the instance:

curl 'https://<your instance>/xrpc/com.example.hello?name=Ada'

A deploy refuses a happyview.lock that doesn’t match happyview.toml. Run hpy happyview dev or check once to bring it up to date, and commit it.

What a deploy changes, and what it doesn’t

A deploy changes:

• lexicons, scripts, modules and tests from src/;
• per-lexicon and per-script settings from happyview.toml;
• labeler subscriptions and network lexicons;
• plugins, from happyview.lock.

A deploy leaves alone:

• the instance’s HappyView version;
• [instance], [dev] and [jetstream] (it warns about [instance] keys that differ from the instance’s, and about [dev] and [jetstream] when they’re set);
• operators, permissions, API clients and keys;
• plugins the lock doesn’t list, unless you pass --prune-plugins;
• lexicons and scripts added in the dashboard (where your project has the same one, the project’s is used);
• ctx.env values: set those under System > ENV Variables on the instance.

Deploy from CI

In CI, hpy uses an API key instead of a sign-in. Create one on the instance under Access > API Keys with these permissions:

• project:deploy
• plugins:read and plugins:create
• plugins:delete too, if you deploy with --prune-plugins

Then give the job the instance’s URL and the key:

Variable	Value
HPY_HV_URL	The instance’s URL
HPY_HV_API_KEY	The API key

In GitHub, set HPY_HV_URL as a repository variable and HPY_HV_API_KEY as a repository secret, under Settings > Secrets and variables > Actions. This workflow checks and tests every push, and deploys main:

name: Deploy

on:
  push:
    branches: [main]
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install hpy
        run: |
          curl -fsSL https://happyproto.github.io/cli/install-beta.sh | sh
          echo "${CARGO_HOME:-$HOME/.cargo}/bin" >> "$GITHUB_PATH"

      - name: Check
        run: hpy happyview check --locked

      - name: Test
        run: hpy happyview test --locked

      - name: Deploy
        if: github.ref == 'refs/heads/main'
        run: hpy happyview deploy --yes
        env:
          HPY_HV_URL: ${{ vars.HPY_HV_URL }}
          HPY_HV_API_KEY: ${{ secrets.HPY_HV_API_KEY }}

• check builds the project the way the instance will, and fails on any problem: exit code 0 if it builds, 1 if it doesn’t, 2 if it can’t run.
• test runs your tests: 0 if they all pass, 1 if any fail or none ran, 2 for a usage, plugin or build problem.
• --locked fails if happyview.lock isn’t up to date, so CI never runs plugins you didn’t commit.

Next steps

• Backfill: watch the backfills a deploy starts.
• Configuration reference: the settings an instance takes from its environment.