FlowSpace Docs
Main Site Hlavná stránka
[ 03 ] DOCKER DEPLOYMENT NASADENIE CEZ DOCKER

Run FlowSpace in Docker. Spusti FlowSpace v Dockeri.

From first-time Docker user to a running server — what Docker is, how to prepare a box, which env vars matter, and how the official image will work once published. Od prvého stretnutia s Dockerom po bežiaci server — čo Docker je, ako pripraviť stroj, ktoré env premenné sú dôležité a ako bude fungovať oficiálny image po zverejnení.

[ 3.1 ]What is DockerČo je Docker

Docker packages applications with all their dependencies into isolated boxes called containers. A container is like a tiny virtual computer that carries its own libraries, language runtime and configuration — but it starts in seconds and runs anywhere Docker is installed. Docker zabalí aplikáciu spolu so všetkými závislosťami do izolovanej „krabice“ — kontajnera. Kontajner je ako malý virtuálny počítač, ktorý si nesie vlastné knižnice, runtime a konfiguráciu — ale štartuje v sekundách a beží všade, kde je nainštalovaný Docker.

  • Image — an immutable recipe (your app + runtime). You pull or build it once.Image — nemenný recept (aplikácia + runtime). Stiahneš alebo zostavíš raz.
  • Container — a running instance of an image.Container — bežiaca inštancia image-u.
  • Compose — a YAML file (docker-compose.yml) that starts multiple containers together (e.g. API + DB + frontend).Compose — YAML súbor (docker-compose.yml), ktorý spustí viac kontajnerov naraz (napr. API + DB + frontend).
  • Volume — persistent storage outside the container so data survives restarts.Volume — trvalé úložisko mimo kontajnera, takže dáta prežijú reštart.
Why it matters: no more “works on my machine”. The same image runs locally, in CI and on the server. Prečo to záleží: už žiadne „u mňa to funguje“. Ten istý image beží lokálne, v CI aj na serveri.

[ 3.2 ]Install DockerNainštaluj Docker

  • macOS / Windows — Docker Desktop. Includes Compose v2.macOS / Windows — Docker Desktop. Obsahuje Compose v2.
  • Linux (Ubuntu / Debian) — official convenience script:Linux (Ubuntu / Debian) — oficiálny inštalačný skript:
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
docker --version
docker compose version

[ 3.3 ]Prepare a serverPriprav server

  1. Provision a Linux box (Ubuntu 22.04+ recommended, 1 vCPU / 2 GB RAM minimum).Priprav si Linux stroj (odporúča sa Ubuntu 22.04+, minimálne 1 vCPU / 2 GB RAM).
  2. Install Docker Engine and Compose (see 3.2).Nainštaluj Docker Engine a Compose (viď 3.2).
  3. Open firewall ports: 22 (SSH), 80 (HTTP), 443 (HTTPS). Do not expose 5432 publicly.Otvor porty firewalu: 22 (SSH), 80 (HTTP), 443 (HTTPS). Nezverejňuj 5432.
  4. Point DNS A record of your domain to the server IP (for example app.example.com).Nasmeruj DNS A záznam domény na IP servera (napr. app.example.com).
  5. Put Nginx or Caddy in front of Docker for TLS and a clean domain. Certbot works well with Nginx.Pred Docker postav Nginx alebo Caddy pre TLS a čistú doménu. Pre Nginx dobre funguje Certbot.

[ 3.4 ]Configure .envKonfiguruj .env

The project reads a single .env at the repo root. For Docker, a few values must change vs. local. Projekt číta jediný .env v koreňovom adresári. Pre Docker sa pár hodnôt líši od lokálneho behu. 

# REQUIRED
DB_URL=postgresql+psycopg://admin:admin@db:5432/flowspace
SECRET_KEY=replace_with_a_long_random_secret

# RUNTIME
RUN_MIGRATIONS=true
BACKEND_HOST=0.0.0.0
BACKEND_PORT=8000
CORS_ORIGINS=https://app.example.com

# STORAGE
FILES_DIR=/data/files
FILES_HOST_DIR=./.docker-data/files

# OPTIONAL OAUTH (shows buttons only when set)
# GOOGLE_CLIENT_ID=
# GOOGLE_CLIENT_SECRET=
# GITHUB_CLIENT_ID=
# GITHUB_CLIENT_SECRET=
VariablePremenná Why it matters in DockerPrečo je dôležitá v Dockeri
DB_URLHost must be db (service name), not localhost.Host musí byť db (názov služby), nie localhost.
BACKEND_HOSTMust be 0.0.0.0 so FastAPI listens on all container interfaces.Musí byť 0.0.0.0, aby FastAPI počúval na všetkých rozhraniach kontajnera.
RUN_MIGRATIONSSet true for first deploy so Alembic creates tables.Pri prvom nasadení nastav true, aby Alembic vytvoril tabuľky.
CORS_ORIGINSComma-separated list of allowed frontend origins (exact URLs, https).Čiarkami oddelený zoznam povolených origin-ov frontendu (presné URL, https).
FILES_HOST_DIRHost folder bind-mounted into the API container for user files.Priečinok na hoste, ktorý sa pripojí do API kontajnera pre súbory používateľov.
SECRET_KEYLong random string. Rotate if leaked. Never commit.Dlhý náhodný reťazec. Pri úniku rotuj. Nikdy necommituj.

[ 3.5 ]Docker Compose (from source)Docker Compose (zo zdrojov)

The repo ships a ready docker-compose.yml with three services: db, api, frontend. Repozitár obsahuje pripravený docker-compose.yml s tromi službami: db, api, frontend. 

git clone <repo-url> flowspace
cd flowspace
cp .env.example .env
# edit .env as described in 3.4
docker compose up -d --build

Verify and open: Over a otvor: 

docker compose ps
docker compose logs -f api
# Frontend: http://localhost:5173
# API:      http://localhost:8000/docs

Everyday Compose commands:Bežné Compose príkazy:

ActionAkcia CommandPríkaz
Start stackSpusti stackdocker compose up -d --build
Stop stackZastav stackdocker compose down
Tail logsSleduj logydocker compose logs -f api
Shell into APIShell do APIdocker compose exec api bash
Run migration manuallySpusti migráciu manuálnedocker compose exec api alembic -c backend/alembic.ini upgrade head
Rebuild one servicePrebuilduj službudocker compose build api && docker compose up -d api

[ 3.6 ]Pre-built image (coming soon)Hotový image (pripravuje sa)

Once published, you will be able to pull a pre-built container image and run FlowSpace without cloning the repository. The pattern will look like this: Po zverejnení si budeš môcť stiahnuť pripravený image a spustiť FlowSpace bez klonovania repozitára. Postup bude vyzerať takto: 

# PLACEHOLDER — exact image name will be announced here.
#
# docker pull ghcr.io/<owner>/flowspace:latest
# docker run -d \
#   --name flowspace \
#   --env-file .env \
#   -p 8000:8000 -p 5173:5173 \
#   ghcr.io/<owner>/flowspace:latest
The image registry, tag names and recommended docker run/docker compose snippet will be filled in here as soon as the first release is published. Until then, use the “from source” flow in section 3.5. Registry, názvy tagov a odporúčaný docker run/docker compose doplníme sem hneď ako vyjde prvý release. Dovtedy použi spustenie „zo zdrojov“ v sekcii 3.5.

[ 3.7 ]Reverse proxy & TLSReverzná proxy a TLS

Recommended layout: Odporúčaná schéma:

  • app.example.com → Nginx/Caddy → frontend:5173app.example.com → Nginx/Caddy → frontend:5173
  • api.example.com → Nginx/Caddy → api:8000api.example.com → Nginx/Caddy → api:8000
  • Issue certificates with Certbot (Nginx) or automatic TLS (Caddy).Vystav certifikáty cez Certbot (Nginx) alebo automatické TLS (Caddy).
Never expose database port 5432 to the internet. Keep it on the internal Docker network only. Nikdy nevystavuj DB port 5432 do internetu. Nechaj ho iba na internej Docker sieti.

[ 3.8 ]Post-deploy checksKontroly po nasadení

  • https://api.example.com/docs opens the Swagger UI.https://api.example.com/docs otvorí Swagger UI.
  • Registration and login work on the real domain.Registrácia a login fungujú na reálnej doméne.
  • No CORS errors in browser console.V konzole prehliadača nie sú CORS chyby.
  • docker compose logs api has no startup exceptions.docker compose logs api neobsahuje chyby pri štarte.
© 2026 FlowSpace / DockerDocker