Configuration

Important settings you may want to change first

absolutely set these in .env before start the instance for the first time:

NEODB_SECRET_KEY - 50 characters of random string, no white space
NEODB_SITE_NAME - the name of your site
NEODB_SITE_DOMAIN - the domain name of your site

NEODB_SECRET_KEY and NEODB_SITE_DOMAIN must not be changed later.

if you are doing debug or development:

NEODB_DEBUG - True will turn on debug for both neodb and takahe, turn off relay, and reveal self as debug mode in nodeinfo (so peers won't try to run fedi search on this node)
NEODB_IMAGE - the docker image to use, neodb/neodb:edge for the main branch

Settings for customization

NEODB_SITE_LOGO
NEODB_SITE_ICON
NEODB_USER_ICON
NEODB_SITE_INTRO
NEODB_SITE_HEAD
NEODB_SITE_DESCRIPTION
NEODB_PREFERRED_LANGUAGES - preferred languages when importing titles from 3rd party sites like TMDB and Steam, comma-separated list of ISO-639-1 two-letter codes, en,zh by default. It can includes languages with no UI translations yet, e.g. if set to ja,en,zh, NeoDB scraper will fetch catalog metadata in three languages if they are available from third party sites, Japanese users (= whose browser language set to ja-JP) will see English UI with Japanese metadata.
NEODB_DISCOVER_FILTER_LANGUAGE - False by default; when set to True, /discover/ will only show items with languages match one of NEODB_PREFERRED_LANGUAGES.
NEODB_DISCOVER_SHOW_LOCAL_ONLY - False by default; when set to True, only show items marked by local users rather than entire network on /discover/
NEODB_DISCOVER_UPDATE_INTERVAL - minutes between each update for popular items on /discover/
NEODB_SITE_LINKS - a list of title and links to show in the footer, comma separated, e.g. Feedback=https://discord.gg/8KweCuApaK,ToS=/pages/rules/
NEODB_INVITE_ONLY - False by default, set to True to require invite code(generated by neodb-manage invite --create) to register
NEODB_ENABLE_LOCAL_ONLY - False by default, set to True to allow user to post marks as "local public"
NEODB_LOGIN_MASTODON_WHITELIST - a list of Mastodon instances to allow login from, comma separated
NEODB_ADMIN_USERNAMES - a list of usernames to be admin, comma separated, server restart is required to apply this setting after these users are registered.
NEODB_EMAIL_FROM - the email address to send email from
NEODB_EMAIL_URL - email sender configuration, e.g.
- smtp://<username>:<password>@<host>:<port>
- smtp+tls://<username>:<password>@<host>:<port>
- smtp+ssl://<username>:<password>@<host>:<port>
- anymail://<anymail_backend_name>?<anymail_args>, to send email via email service providers, see anymail doc
DISCORD_WEBHOOKS - Discord channel to send notification about user submitted suggestion and changes, e.g. suggest=https://discord.com/api/webhooks/123/abc,audit=https://discord.com/api/webhooks/123/def

Settings for Federation

NEODB_SEARCH_PEERS is empty by default, which means NeoDB will search all known peers running production version of NeoDB when user look for items. This can be set to a comma-separated list of host names, so that NeoDB will only search those servers; or search no other peers if set to just -.
NEODB_DISABLE_DEFAULT_RELAY is set to False by default, the server will send and receive public posts from relay.neodb.net.

relay.neodb.net is open sourced and operated by NeoDB developers, it works like most ActivityPub relays except it only relays between NeoDB instances, it helps public information like catalogs and trends flow between NeoDB instances. You may set it to True if you don't want to relay public posts with other NeoDB instances.

Settings for external item sources

SPOTIFY_API_KEY - base64('CLIENT_ID:SECRET'), see spotify doc
TMDB_API_V3_KEY - API v3 key from TMDB
GOOGLE_API_KEY - API key for Google Books
DISCOGS_API_KEY - personal access token from Discogs
IGDB_API_CLIENT_ID, IGDB_API_CLIENT_SECRET - IGDB keys

Other maintenance tasks

Add alias to your shell for easier access

alias neodb-manage='docker-compose --profile production run shell neodb-manage'

Run without Docker

It's currently possible but quite cumbersome to run without Docker, hence not recommended. However it's possible to only use docker to run neodb server but reuse existing PostgresQL/Redis/Typesense servers with compose.override.yml, an example for reference:

services:
  redis:
    profiles: ['disabled']
  typesense:
    profiles: ['disabled']
  neodb-db:
    profiles: ['disabled']
  takahe-db:
    profiles: ['disabled']
  migration:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
  neodb-web:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
    healthcheck: !reset {}
  neodb-web-api:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
    healthcheck: !reset {}
  neodb-worker:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
  neodb-worker-extra:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
  takahe-web:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
  takahe-stator:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
  shell:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
  root:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
  dev-neodb-web:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
  dev-neodb-worker:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
  dev-takahe-web:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
  dev-takahe-stator:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
  dev-shell:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []
  dev-root:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on: !reset []

(extra_hosts is only needed if PostgresQL/Redis/Typesense is on your host server)

Multiple instances on one server

It's possible to run multiple clusters in one host server with docker compose, as long as NEODB_SITE_DOMAIN, NEODB_PORT and NEODB_DATA are different.

Scaling up

For high-traffic instance, spin up these configurations to a higher number, as long as the host server can handle them:

NEODB_WEB_WORKER_NUM
NEODB_API_WORKER_NUM
NEODB_RQ_WORKER_NUM
TAKAHE_WEB_WORKER_NUM
TAKAHE_STATOR_CONCURRENCY
TAKAHE_STATOR_CONCURRENCY_PER_MODEL

Further scaling up with multiple nodes (e.g. via Kubernetes) is beyond the scope of this document, but consider run db/redis/typesense separately, and then duplicate web/worker/stator containers as long as connections and mounts are properly configured; migration only runs once when start or upgrade, it should be kept that way.