GitHub

Self-hosting

Run Biinge on your own server.

Run the Go API with PostgreSQL and Redis, then connect the native iOS app. The steps below create a local development stack; review the production checklist before exposing it to the internet.

Before you start

  • Docker with Compose — runs Postgres, Redis and the API
  • A free TMDB v4 read access token — provides movie and TV search, details and trending
  • A Twitch application client ID and secret — gives the API access to IGDB game data
  • goose — applies database migrations
  • Xcode 26 — to build the iOS app
  1. 1

    Clone the repo

    bash 
    git clone https://github.com/tab/biinge.git
cd biinge
  2. 2

    Add your API keys

    Create api/.env.development.local for your credentials. The file is gitignored and loaded after the committed development defaults, whether the API runs in Docker or directly.

    env 
    # api/.env.development.local — gitignored, never commit it
TMDB_API_READ_ACCESS_TOKEN=<your TMDB v4 read token>
IGDB_CLIENT_ID=<your Twitch app client id>
IGDB_CLIENT_SECRET=<your Twitch app client secret>
JWT_SECRET_KEY=<32+ random bytes>

    In development, missing IGDB credentials leave saved games available but return no game search results. Other environments will not start without them.

  3. 3

    Bring up the stack

    bash 
    # 1. datastores first
docker compose up -d database redis

# 2. apply migrations (needs goose installed)
make -C api db:migrate

# 3. then the API, on :8080
docker compose up -d api

    To run only the API outside Docker, use cd api && GO_ENV=development go run ./cmd/biinge. If you have Fuku installed, fuku up starts it and waits on /ready. The health endpoints are GET /live for liveness and GET /ready for readiness.

  4. 4

    Connect and build the app

    Open ios/Biinge.xcodeproj in Xcode 26 and run it on a simulator or your own device. To check it compiles without leaving the terminal:

    bash 
    # compile the app against your API
make -C ios build

    The app targets http://localhost:8080/api/v1 by default. To point it somewhere else, copy ios/.env.example to ios/.env and set API_BASE_URL — on a real device that has to be a host the phone can reach, not localhost.

Configuration

These are the settings you are most likely to change. The complete development defaults live in api/.env.development.

VariablePurpose
GO_ENV Selects the environment file and validation rules; defaults to development
APP_ADDRESS Address and port the API listens on, such as 0.0.0.0:8080
TMDB_API_READ_ACCESS_TOKEN TMDB v4 read token for movie and TV search, details and trending
IGDB_CLIENT_ID / IGDB_CLIENT_SECRET Twitch application credentials used to access IGDB game data; required outside development
DATABASE_DSN Postgres connection string
REDIS_URL Redis URL for the metadata cache; leave it unset to run without caching
JWT_SECRET_KEY Signs and verifies access tokens; must be at least 32 bytes outside development
CLIENT_URL Adds an HTTPS client origin to the API's CORS allowlist
WORKER_SYNC_ENABLED / WORKER_SYNC_INTERVAL Controls the background TMDB refresh worker and how often it runs
SENTRY_DSN Error reporting (optional)

Before exposing the API

The Compose stack above is for local development. It uses default database credentials, publishes the database and Redis ports, and serves the API over plain HTTP. A public deployment needs at least:

  • GO_ENV=production, complete production environment values, a random JWT_SECRET_KEY of at least 32 bytes, and a unique PostgreSQL password
  • A reverse proxy terminating TLS in front of the API; if a browser client calls it, add that HTTPS origin to CLIENT_URL
  • The database and Redis ports unpublished, reachable only on the Compose network
  • Backups of the Postgres volume, and a plan for applying migrations on upgrade