Beskos
Kod źródłowy

Wdrożenie własne

Configure your instance

The variables that matter, and the ones production refuses to start without.

Zaktualizowano:

Niniejsze tłumaczenie ma charakter informacyjny. W przypadku jakichkolwiek rozbieżności wiążąca jest wersja angielska.

Ten artykuł nie został jeszcze przetłumaczony na Państwa język, więc czytają Państwo wersję angielską. Tłumaczenie jest w drodze.
Spis treści

Configuration is entirely environment variables; there is no configuration file to edit and no secret in the code. Each optional feature is switched on by filling in its own variables and stays off, silently and safely, when they are empty. The repository ships the full generated list in docs/configuration.md; the ones that decide whether an instance starts, and whether it starts securely, are below.

Always required

Without DATABASE_URL the backend does not start at all. The rest of this group is what an instance needs to do anything useful.

  • DATABASE_URL — the PostgreSQL connection string
  • STALWART_URL and STALWART_ADMIN_SECRET — the mail server and the credential the backend uses to administer it
  • MFA_ENC_KEY — encrypts the second-factor secret and the brokered mailbox credential at rest
  • PUBLIC_URL — the address used to build links that leave the application, such as a meeting invitation in an e-mail
DATABASE_URL=postgres://beskos:<password>@postgres:5432/beskos?sslmode=disable
STALWART_URL=http://stalwart:8080
STALWART_ADMIN_SECRET=<32 random bytes, base64>
MFA_ENC_KEY=<48 random bytes, base64>
PUBLIC_URL=https://app.example.org

# Production refuses to start without these three.
APP_ENV=production
COOKIE_SECURE=true
NOTIFY_SMTP_INSECURE=false

Production fails closed

With APP_ENV=production the backend refuses to boot rather than starting in an insecure state. It rejects a secret that is empty, shorter than sixteen characters, or one of the known development defaults such as devkey.

It also requires COOKIE_SECURE=true, NOTIFY_SMTP_INSECURE=false and DEV_SIGNUP_ENABLED=false. The last one is not cosmetic: left on, it exposes unauthenticated, unlimited organisation creation.

A forgotten secret that stops the boot costs minutes. One that is silently accepted ships an instance somebody else can take over.

Storage and realtime

Object storage holds uploaded files and attachments. Any S3-compatible service works; the compose file runs MinIO for a first install.

  • MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_BUCKET, MINIO_REGION, MINIO_SSL
  • FILE_ENC_KEYS — encrypts uploaded files at rest. Without it storage works and files are stored in the clear
  • REDIS_URL — required for chat to update in real time across sessions

Features that stay off until configured

None of these stop mail, calendar or files from working. Each adds one capability, and the startup log states which ones came up and which did not.

  • AI_API_KEY, AI_PROVIDER, AI_BASE_URL and AI_MODEL — the assistant, on any OpenAI-compatible endpoint: a vendor's API, or a local runtime such as Ollama or vLLM on the same network
  • EMBEDDINGS_API_KEY, EMBEDDINGS_BASE_URL and EMBEDDINGS_MODEL — semantic search in the wiki
  • LIVEKIT_URL, LIVEKIT_API_KEY and LIVEKIT_API_SECRET — video meetings, and recording with the egress service
  • ONLYOFFICE_URL, ONLYOFFICE_JWT_SECRET and DOC_TOKEN_SECRET — editing Office documents in the browser
  • NOTIFY_SMTP_HOST and NOTIFY_FROM — outbound notifications: password resets, new-device alerts, external shares
  • VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY — push notifications while the application is closed
  • EDITION_LICENSE_KEY and EDITION_PUBLIC_KEY — a Pro key, verified offline

Choosing the AI endpoint

The assistant uses the OpenAI-compatible chat API, which most vendors and local runtimes implement. AI_PROVIDER is a label for the logs. The names deepseek, tensorx, openai and ollama also supply the address; any other name requires AI_BASE_URL. AI_MODEL is required except with deepseek and tensorx, which carry a default.

The endpoint determines where the content is processed when the assistant is used. A local runtime processes it inside the installation. Ollama requires no key; AI_API_KEY still has to hold a value, because an empty key is what switches the assistant off.

  • AI_PROVIDER=openai, AI_MODEL=gpt-4o-mini
  • AI_PROVIDER=ollama, AI_MODEL=llama3.1, AI_API_KEY set to any value
  • AI_PROVIDER=groq, AI_BASE_URL=https://api.groq.com/openai/v1, AI_MODEL=llama-3.3-70b-versatile

One obligation that is not technical

The document editor is a modified build of OnlyOffice, which is licensed under the AGPL. Section 13 of that licence requires whoever serves it to tell their users where the modified source is. ONLYOFFICE_SOURCE_URL carries that address, and production refuses to start with the editor enabled unless it is set explicitly.

It has to point at your own fork if you changed the build. Leaving it at the default publishes a notice sending your users to somebody else's repository, which does not discharge the obligation.

Keys to settle on the first day

MFA_ENC_KEY and FILE_ENC_KEYS protect data at rest, and changing them later invalidates what they already protect: rotating the first invalidates every enrolled second factor. Generate them once, keep them stable, and back them up somewhere other than the server they are used on.

Dalej: Add your domain →