Osvědčené postupy

Rozvržení adresáře aplikace

Dodržujte konzistentní rozvržení adresáře, abyste zajistili udržovatelnost a kompatibilitu. Všechny nevložené aplikace (oficiální i třetích stran) se instalují na úložné svazky do /Volume*/@apps/<appid>/.

Standardní rozvržení adresáře:

/Volume*/@apps/<appid>/
├── <binary> # Application executable
├── config.ini        # Application configuration file
├── <appid>.lang      # Language file
├── images/           # Icon resources
├── webui.bz2         # Front-end page archive (WebUI applications)
├── nginx/            # Nginx configuration (externally opened applications)
├── init.d/           # Systemd service files
├── data/             # Runtime data (caches, temporary files, writable)
└── logs/             # Application logs

Poznámka: * v /Volume*/ představuje číslo svazku (např. Volume1, Volume2) zvolené uživatelem při instalaci.

Doporučení pro ukládání dat:

Běhová data (/Volume*/@apps/<appid>/data/) — Mezipaměti generované aplikací, dočasné soubory a běhový stav. Tato data lze bezpečně regenerovat.
Protokoly (/Volume*/@apps/<appid>/logs/) — Soubory protokolů aplikace. Zajistěte konfiguraci rotace protokolů.
Uživatelská obchodní data — Musí být uložena ve sdílených složkách pod /Volume*/ (např. /Volume*/<appid>/), aby k nim uživatelé měli přístup přes SMB/NFS.

Perzistence dat

Porozumění typům dat:

Typ dat	Cesta	Popis
Běhová data	`/Volume*/@apps/<appid>/data/`	Mezipaměti, dočasné soubory, běhový stav (lze regenerovat)
Uživatelská data	`/Volume*/<appid>/` (sdílená složka)	Perzistentní obchodní data (musí přežít upgrady aplikace)

Aplikace Deb:

Běhová data se ukládají do /Volume*/@apps/<appid>/data/

Uživatelská data musí být uložena ve sdílené složce vytvořené aplikací:

# In postinst — create a shared folder for user data
ter_share_add -name <appid> -owner <appid>

Pro zachování kompatibility může aplikace vytvořit symbolické odkazy:
```
ln -s /Volume*/<appid> /Volume*/@apps/<appid>/data
```
Sdílená složka /Volume*/<appid>/ je přístupná uživatelům přes SMB/NFS

Aplikace Docker:

Připojte konfiguraci a běhová data do /Volume*/DockerAppData/<appid>/:

Volumes:
  - /Volume*/DockerAppData/<appid>/config:/config
  - /Volume*/DockerAppData/<appid>/cache:/cache

Uživatelská data musí být uložena ve sdílené složce:
```
Volumes:
  - /Volume*/<appid>:/data
```
Ukládání dat do souborového systému kontejneru je zakázáno
Používejte samostatné svazky pro konfiguraci a data, abyste podpořili nezávislé zálohování

Poznámka: * v /Volume*/ představuje číslo svazku (např. Volume1, Volume2) zvolené uživatelem při instalaci.

Běhová data lze bezpečně smazat bez ztráty uživatelských obchodních dat

Uživatelská data (sdílená složka) musí být před upgrady aplikace zazálohována

Protokolování

Aplikace Deb:

# Use systemd journal (recommended)
# All stdout/stderr from the service is automatically captured
# View logs: journalctl -u <appid>

# Or write to file
exec >> /Volume*/@apps/<appid>/logs/app.log 2>&1

Aplikace Docker:

services:
  myapp:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Poznámka: Každý soubor protokolu kontejneru je omezen na 10MB, uchovávají se 3 soubory, celkový strop velikosti protokolů je 30MB.

Osvědčené postupy:

Používejte strukturované protokolování (doporučuje se formát JSON)
Do každého záznamu protokolu zahrňte časové razítko, úroveň a kontext
Rotujte protokoly, abyste zabránili vyčerpání disku
Nikdy neprotokolujte citlivé informace (hesla, tokeny, osobní údaje)

Uchovávání a čištění protokolů:

Typ protokolu	Maximální uchování	Metoda čištění
Protokoly aplikace (soubory)	30 dnů	Logrotate: denní rotace, uchování 30 souborů
Systemd Journal	Spravováno platformou	Automaticky spravováno přes limity journald
Protokoly kontejnerů Docker	10MB na soubor, celkem 3 soubory	Konfigurace ovladače protokolování Docker

Konfigurace Logrotate:

/Volume*/@apps/<appid>/logs/*.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

Limity prostředků

Prostředek	Aplikace Deb (systemd)	Aplikace Docker (compose)
Paměť	`MemoryMax=512M`	`memory: 512M`
CPU	`CPUQuota=200%`	`cpus: '2.0'`
Deskriptory souborů	`LimitNOFILE=65536`	N/A (úroveň kontejneru)
Procesy	`LimitNPROC=256`	N/A (úroveň kontejneru)
Disk	N/A (použijte kvóty)	Limit velikosti svazku

Pokyny:

Nastavte limity prostředků na základě očekávané zátěže, ne maximálního možného využití
Rezervujte 20–30% rezervu pro špičky nad běžným využitím
Zdokumentujte požadavky na prostředky v README.md

Kontroly stavu

Aplikace Deb:

# In systemd service file
[Service]
StartLimitBurst=3
StartLimitIntervalSec=60

# Watchdog (if application supports it)
WatchdogSec=30

Aplikace Docker:

services:
  myapp:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

Upgrady a migrace

Aplikace Deb:

V postinst vždy zkontrolujte staré verze:

if [ -n "$2" ]; then
    # Upgrading from $2 — run migration
    /Volume*/@apps/<appid>/bin/migrate --from "$2"
fi

Během upgradů nikdy nemažte uživatelská data
Před úpravou formátů konfigurace proveďte zálohu
Migrační logika by měla být vratná, aby podporovala návrat
Uživatelům se doporučuje ukládat data do /Volume*/@apps/<appid>/data/ nebo do /Volume*/, aby po upgradech nedošlo ke ztrátě dat

Aplikace Docker:

Použijte vstupní skript pro detekci a migraci starých datových formátů:

#!/bin/bash
if [ -f /config/version ]; then
    OLD_VERSION=$(cat /config/version)
    if [ "$OLD_VERSION" != "$NEW_VERSION" ]; then
        /app/migrate.sh "$OLD_VERSION" "$NEW_VERSION"
    fi
fi
echo "$NEW_VERSION" > /config/version

Otestujte cesty upgradu alespoň pro poslední 2 hlavní verze

Posílení zabezpečení

Aplikace Deb:

[Service]
# Drop all capabilities, add only required ones
AmbientCapabilities=CAP_NET_BIND_SERVICE
NoNewPrivileges=true

# File system protection
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/Volume*/@apps/<appid>/data /Volume*/@apps/<appid>/logs

> **Poznámka:** Pokud aplikace potřebuje zapisovat konfigurační soubory pod `/etc`, musí pomocí `ReadWritePaths` explicitně deklarovat zapisovatelné cesty.

# Network namespace (optional)
# PrivateNetwork=true  # Only when network is not needed

# User namespace
# PrivateUsers=true

Aplikace Docker:

services:
  myapp:
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE  # Only when binding to ports below 1024
    read_only: true
    tmpfs:
      - /tmp
      - /run

Povinné (musí obsahovat každé podání):

NoNewPrivileges=true

ProtectSystem=strict

ProtectHome=true

ReadWritePaths (pouze explicitní cesty)

Nerootový User/Group

Doporučené (důrazně navrhované):

AmbientCapabilities (pouze potřebné capabilities)

LimitNOFILE, LimitNPROC

PrivateTmp=true

PrivateDevices=true

Volitelné (pokročilé posílení):

PrivateNetwork=true (pouze když není síť potřeba)

PrivateUsers=true

MemoryDenyWriteExecute=true

Přidělování portů aplikace

Pravidla:

Přednostně vybírejte porty v doporučeném rozsahu 8000-19999 (celkem 12 000 portů, výrazně snižuje pravděpodobnost konfliktů)
Pokud jsou porty v doporučeném rozsahu obsazené, lze jako alternativu použít 49152-65535 (rozsah dynamických portů).
Před výběrem zkontrolujte běžně používané porty, abyste se vyhnuli konfliktům; porty umožněte konfigurovat přes proměnné prostředí
Zdokumentujte použití portů v README.md

Popis rozsahu portů:

8000-19999: Doporučený rozsah portů pro aplikace TOS 7, vyhýbá se portům základních systémových služeb (jako 22/80/443/8181), s dostatečnou kapacitou pro potřeby portů naprosté většiny aplikací
49152-65535: Rozsah dynamických/soukromých portů definovaný organizací IANA, vhodný pro dočasné nebo záložní scénáře

Referenční seznam běžných portů (vyhněte se použití):

Port	Aplikace
22	SSH
80	TOS Web (HTTP)
443	TOS Web (HTTPS)
445	SMB
3306	MySQL
5050	TOS Daemon
5432	PostgreSQL
6379	Redis
8096	Jellyfin
8181	TOS Nginx
8443	TOS HTTPS
9000	Portainer
9090	Prometheus

Rozvržení adresáře aplikace​

Perzistence dat​

Protokolování​

Limity prostředků​

Kontroly stavu​

Upgrady a migrace​

Posílení zabezpečení​

Přidělování portů aplikace​

Rozvržení adresáře aplikace

Perzistence dat

Protokolování

Limity prostředků

Kontroly stavu

Upgrady a migrace

Posílení zabezpečení

Přidělování portů aplikace