Buuck telepítése VPS-re

A Buuck a saját szervereden fut. Ez az oldal leírja, hogyan telepítsd a Buuckot egy VPS-re.

Kövesd a lépéseket a megadott sorrendben. A telepítés körülbelül 30 percet vesz igénybe.

Mit telepítesz

A Buuck három alkalmazásból és három kiegészítő szolgáltatásból áll. A Docker Compose ezeket együtt indítja el.

Szolgáltatás	Funkció	Port
booking	A nyilvános oldal. Az ügyfeleid itt foglalnak.	3002
dashboard	A privát oldal. A munkatársaid itt kezelik a foglalásokat.	3001
server	Az API. A két alkalmazás innen kapja az adatokat.	3000
postgres	Az adatbázis. Az összes adatot az adatbázis tárolja.	5432
cache	A gyorsítótár. A gyorsítótár gyorsabbá teszi az API-t.	6379
caddy	A reverse proxy. Emellett a TLS-tanúsítványokat is beszerzi.	80, 443

Csak a reverse proxy érhető el az internetről. A többi szolgáltatás privát Docker-hálózaton fut.

Mielőtt elkezded

Ezekre lesz szükséged:

• Egy VPS 2 CPU-maggal, 4 GB RAM-mal és 20 GB szabad lemezterülettel.
• 64 bites x86 processzor. A Buuck image-ek nem futnak ARM processzoron.
• Linux operációs rendszer. A Buuckot Ubuntu 24.04-en teszteljük.
• Root hozzáférés a VPS-hez, vagy sudo jogosultságú felhasználói fiók.
• Egy domainnév. Tudnod kell DNS-rekordokat hozzáadni a zónájához.
• A registry felhasználóneved és a licenckulcsod. Ezeket e-mailben küldjük el.
• A Buuck kiadásod verziószáma. Ugyanaz az e-mail tartalmazza ezt a számot.
• Egy SMTP-fiók. A Buuck ezzel a fiókkal küldi a foglalási e-maileket.

Figyelem

Tartsd titokban a licenckulcsodat. Aki megkapja a licenckulcsodat, az összes Buuck image-hez hozzáférhet.

A licenced csak arra a személyre vagy cégre vonatkozik, aki megvette a Buuckot. Ha egy cég vásárolta meg, csak az a cég használhatja. Ne add át a licenckulcsodat más személynek vagy más cégnek.

Ha nem tartod be ezeket a szabályokat, visszavonjuk a licencedet és a licenckulcsodat. Ekkor elveszíted a hozzáférést a Buuck image-ekhez és az összes későbbi verzióhoz.

Ez az oldal az example.com domainnevet használja. Cseréld le az example.com-ot a saját domainnevedre.

1. lépés: DNS-rekordok hozzáadása

A Buuck három aldomaint használ. Adj hozzá egy DNS A rekordot minden aldomainhez. Minden rekord a VPS-ed IP-címére mutasson.

Rekord	Példa	Szolgáltatás
api	api.example.com	az API
admin	admin.example.com	a dashboard
book	book.example.com	a foglalási oldal

Ha a DNS-szolgáltatódnak van proxy funkciója, kapcsold ki a proxyt. A VPS-eden futó reverse proxynak közvetlenül kell megkapnia a kéréseket.

Ellenőrizz egy rekordot, mielőtt továbblépsz:

dig +short api.example.com

A parancs a VPS-ed IP-címét mutatja. Ha a parancs nem ad vissza címet, várj 10 percet. Ezután ellenőrizd újra.

2. lépés: Docker telepítése

Csatlakozz a VPS-edhez:

ssh root@YOUR-SERVER-IP

Telepítsd a Docker Engine-t és a Docker Compose plugint:

curl -fsSL https://get.docker.com | sh

Ellenőrizd a két verziót:

docker --version
docker compose version

A Docker Compose verziója 2.20 vagy újabb legyen.

Nyisd meg a szükséges portokat a tűzfalon. Az Ubuntu az ufw-t használja:

ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Figyelem

Ne nyisd meg az 5432-es vagy a 6379-es portot. Az adatbázisnak és a gyorsítótárnak privátnak kell maradnia.

3. lépés: Bejelentkezés a Buuck registrybe

A Buuck image-eid egy privát registryben vannak. Jelentkezz be az e-mailben kapott felhasználónévvel és licenckulccsal.

Figyelem

Ted a felhasználónevet szimpla idézőjelek közé. A felhasználónév $ karaktert tartalmaz. A shell törli a nem idézőjelezett $ karaktert.

echo 'YOUR-LICENSE-KEY' | docker login registry.buuck.io -u 'robot$YOUR-LICENSE-ID' --password-stdin

A Docker a Login Succeeded üzenetet mutatja. Ezután a Docker a VPS-en tárolja a licenckulcsot. Ezt a lépést csak egyszer kell megtenned.

4. lépés: Telepítési mappa létrehozása

Hozz létre egy mappát a konfigurációs fájljaidnak:

mkdir -p /opt/buuck
cd /opt/buuck

A következő lépéseket mind ebben a mappában végezd.

5. lépés: Compose fájl létrehozása

Hozz létre egy compose.yaml nevű fájlt. Írd bele ezt a szöveget:

name: buuck

services:
  postgres:
    image: postgres:16-alpine
    container_name: buuck-postgres
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER}']
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped
    networks:
      - buuck

  cache:
    image: valkey/valkey:9.0.0-alpine3.22
    container_name: buuck-cache
    command:
      - valkey-server
      - --requirepass
      - ${CACHE_PASSWORD}
      - --dir
      - /data
      - --save
      - '900 1'
      - --maxmemory
      - 256mb
      - --maxmemory-policy
      - allkeys-lru
    environment:
      CACHE_PASSWORD: ${CACHE_PASSWORD}
    volumes:
      - cache_data:/data
    healthcheck:
      test: ['CMD-SHELL', 'valkey-cli --no-auth-warning -a "$$CACHE_PASSWORD" ping | grep -q PONG']
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped
    networks:
      - buuck

  db-migrate:
    image: ${BUUCK_REGISTRY:-registry.buuck.io}/buuck/db-migrate:${BUUCK_VERSION}
    container_name: buuck-db-migrate
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      APP_DB_USER: ${APP_DB_USER}
      APP_DB_PASSWORD: ${APP_DB_PASSWORD}
      NOTIFICATION_WORKER_USER: ${NOTIFICATION_WORKER_USER}
      NOTIFICATION_WORKER_PASSWORD: ${NOTIFICATION_WORKER_PASSWORD}
    depends_on:
      postgres:
        condition: service_healthy
    restart: 'no'
    networks:
      - buuck

  server:
    image: ${BUUCK_REGISTRY:-registry.buuck.io}/buuck/server:${BUUCK_VERSION}
    container_name: buuck-server
    environment:
      NODE_ENV: production
      DATABASE_URL: postgresql://${APP_DB_USER}:${APP_DB_PASSWORD}@postgres:5432/${POSTGRES_DB}
      DATABASE_NOTIFICATION_WORKER_URL: postgresql://${NOTIFICATION_WORKER_USER}:${NOTIFICATION_WORKER_PASSWORD}@postgres:5432/${POSTGRES_DB}
      CACHE_URL: valkey://:${CACHE_PASSWORD}@cache:6379
      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
      BETTER_AUTH_URL: https://${API_DOMAIN}
      CORS_ORIGIN: https://${DASHBOARD_DOMAIN},https://${BOOKING_DOMAIN}
      EMAIL_PROVIDER: ${EMAIL_PROVIDER}
      EMAIL_FROM: ${EMAIL_FROM}
      SMTP_HOST: ${SMTP_HOST}
      SMTP_PORT: ${SMTP_PORT}
      SMTP_USER: ${SMTP_USER}
      SMTP_PASS: ${SMTP_PASS}
      SMTP_SECURE: ${SMTP_SECURE}
      NOTIFICATION_POLL_INTERVAL_MS: ${NOTIFICATION_POLL_INTERVAL_MS}
    depends_on:
      postgres:
        condition: service_healthy
      cache:
        condition: service_healthy
      db-migrate:
        condition: service_completed_successfully
    restart: unless-stopped
    networks:
      - buuck

  dashboard:
    image: ${BUUCK_REGISTRY:-registry.buuck.io}/buuck/dashboard:${BUUCK_VERSION}
    container_name: buuck-dashboard
    environment:
      NODE_ENV: production
      ORIGIN: https://${DASHBOARD_DOMAIN}
      PUBLIC_SERVER_URL: https://${API_DOMAIN}
    depends_on:
      server:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - buuck

  booking:
    image: ${BUUCK_REGISTRY:-registry.buuck.io}/buuck/booking:${BUUCK_VERSION}
    container_name: buuck-booking
    environment:
      NODE_ENV: production
      ORIGIN: https://${BOOKING_DOMAIN}
      PUBLIC_SERVER_URL: https://${API_DOMAIN}
    depends_on:
      server:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - buuck

  caddy:
    image: caddy:2-alpine
    container_name: buuck-caddy
    environment:
      ACME_EMAIL: ${ACME_EMAIL}
      API_DOMAIN: ${API_DOMAIN}
      DASHBOARD_DOMAIN: ${DASHBOARD_DOMAIN}
      BOOKING_DOMAIN: ${BOOKING_DOMAIN}
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - server
      - dashboard
      - booking
    restart: unless-stopped
    networks:
      - buuck

volumes:
  postgres_data:
    driver: local
  cache_data:
    driver: local
  caddy_data:
    driver: local
  caddy_config:
    driver: local

networks:
  buuck:
    driver: bridge

6. lépés: Reverse proxy fájl létrehozása

A reverse proxy minden kérést a megfelelő szolgáltatáshoz továbbít. Emellett TLS-tanúsítványt is beszerez minden aldomainhez.

Hozz létre egy Caddyfile nevű fájlt. Írd bele ezt a szöveget:

{
  email {$ACME_EMAIL}
}

{$API_DOMAIN} {
  reverse_proxy server:3000
}

{$DASHBOARD_DOMAIN} {
  reverse_proxy dashboard:3001
}

{$BOOKING_DOMAIN} {
  reverse_proxy booking:3002
}

7. lépés: Környezeti fájl létrehozása

A környezeti fájl tartalmazza a domainneveidet, a jelszavaidat és a titkos kulcsodat.

Először készíts öt véletlenszerű értéket. Futtasd le ezt a parancsot ötször:

openssl rand -hex 24

Őrizd meg az öt eredményt. Minden jelszóhoz és a titkos kulcshoz egyet használsz fel.

Hozz létre egy .env nevű fájlt. Írd bele ezt a szöveget. Ezután cseréld le minden példaértéket a saját értékedre:

# Version
BUUCK_VERSION=v0.0.1
BUUCK_REGISTRY=registry.buuck.io

# Domain names
API_DOMAIN=api.example.com
DASHBOARD_DOMAIN=admin.example.com
BOOKING_DOMAIN=book.example.com
ACME_EMAIL=[email protected]

# Database
POSTGRES_DB=buuck
POSTGRES_USER=postgres
POSTGRES_PASSWORD=REPLACE-WITH-RANDOM-VALUE-1
APP_DB_USER=app_user
APP_DB_PASSWORD=REPLACE-WITH-RANDOM-VALUE-2
NOTIFICATION_WORKER_USER=notification_worker_user
NOTIFICATION_WORKER_PASSWORD=REPLACE-WITH-RANDOM-VALUE-3

# Cache
CACHE_PASSWORD=REPLACE-WITH-RANDOM-VALUE-4

# Authentication
BETTER_AUTH_SECRET=REPLACE-WITH-RANDOM-VALUE-5

# Email
EMAIL_PROVIDER=smtp
EMAIL_FROM="Your Business <[email protected]>"
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=
SMTP_PASS=
SMTP_SECURE=false

# Notifications
NOTIFICATION_POLL_INTERVAL_MS=60000

Ezek a legfontosabb változók:

Változó	Funkció
BUUCK_VERSION	A Buuck verziója. Az e-mailed tartalmazza ezt az értéket.
BUUCK_REGISTRY	A Docker registry címe. Alapértelmezés: registry.buuck.io.
API_DOMAIN	Az API címe.
DASHBOARD_DOMAIN	A dashboard címe.
BOOKING_DOMAIN	A foglalási oldal címe.
ACME_EMAIL	Az e-mail címed. A tanúsítványkiadó ide küldi a figyelmeztetéseket.
BETTER_AUTH_SECRET	A felhasználói munkamenetek titkos kulcsa. Indítás után ne változtasd meg.
EMAIL_PROVIDER	Az e-mail fiók típusa. Használd az smtp, sendgrid, postmark vagy resend értéket.
EMAIL_FROM	A foglalási e-mailek feladó címe.

Figyelem

Ne változtasd meg később a BETTER_AUTH_SECRET értékét. Az új titkos kulcs érvénytelenné teszi az összes felhasználói munkamenetet.

Állítsd be a fájl megfelelő jogosultságait. Így csak a tulajdonos olvashatja a jelszavaidat:

chmod 600 .env

Megjegyzés

Az smtp szolgáltató Amazon SES-sel, Mailgunnal és más SMTP-szerverekkel is működik. Más szolgáltatóhoz tedd az API-kulcsát a .env fájlba. Ezután töröld az SMTP_ sorokat.

8. lépés: Buuck indítása

Töltsd le az image-eket a registryből:

docker compose pull

Indítsd el az összes szolgáltatást:

docker compose up -d

A Docker a helyes sorrendben indítja a szolgáltatásokat:

1. Az adatbázis és a gyorsítótár elindul.
2. A db-migrate szolgáltatás létrehozza az adatbázis-felhasználókat és az adatbázis-táblákat. Ezután ez a szolgáltatás leáll.
3. Az API elindul.
4. A dashboard, a foglalási oldal és a reverse proxy elindul.

Az első indítás körülbelül 2 percet vesz igénybe. A reverse proxy ebben az időben a TLS-tanúsítványokat is beszerzi.

Nézd meg a szolgáltatások állapotát:

docker compose ps

A db-migrate szolgáltatás az exited (0) állapotot mutatja. Ez az állapot helyes. A szolgáltatás csak egyszer fut le. Az összes többi szolgáltatás a running vagy healthy állapotot mutatja.

9. lépés: Telepítés ellenőrzése

Küldj egy kérést az API-nak:

curl -i https://api.example.com

Az API 200 OK választ ad, és a szöveg OK.

Ezután nyisd meg ezt a két címet a böngészőben:

• A https://admin.example.com a dashboard bejelentkezési oldalát mutatja.
• A https://book.example.com a foglalási oldalt mutatja.

A böngészőnek érvényes tanúsítványt kell mutatnia minden címhez. Ha egy oldal nem nyílik meg, olvasd el a Problémák szakaszt.

10. lépés: Első fiók létrehozása

1. Nyisd meg a https://admin.example.com címet a böngészőben.
2. Válaszd a Sign up lehetőséget.
3. Add meg a neved, az e-mail címed és egy jelszót.
4. Válaszd a New organization lehetőséget.
5. Add meg a vállalkozásod nevét és egy rövid nevet a címhez.

A dashboard megnyílik. Mostantól hozzáadhatod a helyszíneidet, az erőforrásaidat és a szolgáltatásaidat.

Az ügyfeleid a https://book.example.com/YOUR-SHORT-NAME címen foglalnak.

Mentés készítése

A Buuck az összes adatodat az adatbázisban tárolja. Készíts naponta mentést az adatbázisról.

Írd a mentést egy fájlba:

cd /opt/buuck
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > buuck-$(date +%F).sql

Készíts másolatot a .env fájlról is. Tartsd mindkét fájlt egy másik gépen.

Ha vissza szeretnél tölteni egy mentést az adatbázisba, használd ezt a parancsot:

docker compose exec -T postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' < buuck-2026-01-31.sql

Frissítés telepítése

A licenced tartalmazza az összes későbbi verziót. Minden új verzióról e-mailt küldünk.

Figyelem

Telepítés előtt készíts mentést az adatbázisról.

1. Nyisd meg a .env fájlt.
2. Állítsd a BUUCK_VERSION értékét az új verzióra.
3. Töltsd le az új image-eket:

docker compose pull

4. Indítsd el az új verziót:

docker compose up -d

A Docker csak azokat a szolgáltatásokat cseréli le, amelyekhez új image tartozik. Az adatbázis megőrzi az adataidat.

Buuck leállítása és indítása

Állítsd le az összes szolgáltatást:

cd /opt/buuck
docker compose stop

Indítsd el újra az összes szolgáltatást:

docker compose start

Buuck eltávolítása

A konténerek eltávolításához használd ezt a parancsot:

cd /opt/buuck
docker compose down

Veszély

A következő parancs törli az adatbázisodat. Az összes foglalásod és az összes fiókod elveszik. Először készíts mentést.

docker compose down --volumes

Problémák

Olvasd el egy szolgáltatás üzeneteit. Cseréld le a server nevet a szolgáltatás nevére:

cd /opt/buuck
docker compose logs -f server

Probléma	Ok és javítás
A Docker unauthorized vagy denied üzenetet mutat pull közben.	A bejelentkezés nem érvényes. Csináld meg újra a 3. lépést.
A Docker manifest unknown üzenetet mutat pull közben.	A BUUCK_VERSION értéke nem helyes. Hasonlítsd össze az értéket az e-maileddel.
A Docker exec format error üzenetet mutat egy szolgáltatásnál.	A VPS processzora nem 64 bites x86. Használj másik VPS-t.
A böngésző tanúsítványhibát mutat.	A DNS-rekordok nem helyesek, vagy aktív a proxy. Ellenőrizd azt is, hogy a 80-as port nyitva van-e.
A db-migrate szolgáltatás exited (1) állapotot mutat.	Olvasd el a szolgáltatás üzeneteit. Ezután indítsd újra a docker compose up -d db-migrate paranccsal.
A dashboard kapcsolódási hibát mutat.	Az API_DOMAIN vagy a DASHBOARD_DOMAIN értéke nem helyes. Javítsd az értéket. Ezután futtasd a docker compose up -d --force-recreate parancsot.
Az e-mailek nem érkeznek meg.	Az SMTP értékek nem helyesek. Olvasd el a server szolgáltatás üzeneteit.
Egy szolgáltatás újra és újra elindul.	A .env fájlban van üres érték. Hasonlítsd össze a fájlt a 7. lépés példájával.

Ha a probléma továbbra is fennáll, válaszolj arra az e-mailre, amit a Buuck megvásárlása után küldtünk. Csatold a válaszodhoz a szolgáltatások üzeneteit.