sillyspace/docs/self-hosting.md

Self-Hosting

Bliish.space runs as one Node process with one SQLite database and one upload directory.

Who This Is For

These notes are for both the Bliish maintainers and independent operators. The production process is the same; only the domain name and source repository change.

• Official maintainers deploy bliish.space from bliish-com/bliishspace.
• Independent operators deploy their own domain from their own public fork or copy if they want GitHub auto-deploys.
• Operators who do not want GitHub auto-deploys can deploy the upstream repository directly and run updates manually.

For GitHub auto-deploys, use a repository you control. The deployment helper writes environment secrets and variables to that repository, so a self-hoster normally needs a fork. Keep the fork public unless you intentionally extend the VPS bootstrap with private Git credentials.

Requirements

• Node.js 24 LTS or newer.
• pnpm through Corepack.
• A writable data directory.
• A reverse proxy with TLS for public deployments.

Local Setup

corepack enable
pnpm install
pnpm db:init
pnpm dev

Open http://localhost:3000.

Configuration

Copy .env.example if you want a local starting point, then adjust values for the instance:

BLIISH_BASE_URL=https://bliish.space
BLIISH_DATABASE_PATH=./data/bliish.sqlite
BLIISH_UPLOAD_DIR=./data/uploads
BLIISH_ADMIN_USER_ID=1
BLIISH_MEDIA_CONCURRENCY=1
PORT=3000
HOST=127.0.0.1

The app does not auto-load .env files. Source that file in your shell or process manager before running app commands.

If these variables are unset, the app defaults to http://localhost:3000, ./data/bliish.sqlite, ./data/uploads, admin user id 1, media concurrency 1, port 3000, and host 0.0.0.0. The account that signs up with BLIISH_ADMIN_USER_ID receives the admin role, and all users are kept as accepted friends with that protected admin account.

When group id 1 exists, it is the default group. Existing and new users are added automatically, users cannot leave it, and the group cannot be deleted.

The default app does not require cloud credentials or an email provider. Password reset and verification messages are written to the local email outbox visible to admins.

BLIISH_UPLOAD_DIR controls where uploads are written. Public user media is served only from the profile-image, post-image, and theme-song buckets at /media/pfp/*, /media/post-images/*, and /media/theme-songs/*. Keep the upload directory on persistent storage and include it in backups.

Uploaded user images are normalized locally before storage. BLIISH_MEDIA_CONCURRENCY controls sharp/libvips worker concurrency and defaults to 1, which keeps memory and CPU predictable on small VPS instances.

Admin Console

After the admin account signs in, open /admin to manage the instance without editing source code.

Admins can manage users, reports, automod rules, rate limits, site identity, home page text, contact and legal details, announcements, color theme, blog cleanup, favorites cleanup, the local email outbox, database table counts, and the audit log. Moderators can use /moderation/reports for report handling.

Admin-managed instance settings are runtime data, not source files. They are stored in the SQLite database, so updating application code should not overwrite them. The defaults in the repository are fallbacks for a fresh database or an intentional reset.

Production Process

Build and run:

pnpm install --frozen-lockfile
pnpm db:init
pnpm build
pnpm start

Use a process manager such as systemd, OpenRC, runit, s6, or Docker if that fits the operator environment. Docker should remain optional.

Provider Recipes

• Hetzner Cloud CLI
• Hetzner Cloud manual VPS

For GitHub-based auto-deploys, self-hosters should fork or copy the repository first. The VPS pulls code from BLIISH_REPOSITORY_URL, and setup-github.sh writes deploy secrets to BLIISH_GITHUB_REPOSITORY, so those values should point at a repository the operator controls.

For manual updates without GitHub deploys, a self-hoster may keep BLIISH_REPOSITORY_URL=https://github.com/bliish-com/bliishspace.git, skip setup-github.sh, and run the update command from the deployment guide when they want to pull upstream.

Reverse Proxy

Terminate TLS at the reverse proxy and forward to the local app port.

Example nginx shape:

server {
  server_name bliish.space;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
  }
}

Backups

Back up both:

• the SQLite database;
• the upload directory.

The SQLite database includes users, posts, moderation records, and admin branding/settings. The upload directory includes profile images, post images, and theme songs.

For a small instance, the simplest backup is:

1. Stop the app.
2. Copy data/bliish.sqlite.
3. Copy data/uploads/.
4. Start the app.

For live backups, use SQLite's backup tooling or a filesystem snapshot that handles WAL files correctly.

sqlite3 data/bliish.sqlite ".backup 'backup/bliish.sqlite'"

Restore

1. Stop the app.
2. Restore the SQLite database file.
3. Restore data/uploads/.
4. Check ownership and permissions.
5. Start the app.
6. Open /home, /u/<handle>, and /account/export.json for a smoke test.

Operational Notes

• Keep the database and uploads out of the public repository.
• Keep BLIISH_BASE_URL accurate so secure cookies work behind TLS.
• Do not put uploads on a filesystem that silently drops writes.
• Monitor disk usage.
• Keep OS packages patched.
• Publish instance-specific privacy, moderation, and backup policies.