Instalacja React + Vite

Instalacja

Instrukcja opisuje wdrożenie frontendowej aplikacji Mantine Web (React + Vite) w środowisku Docker w dwóch trybach:

DEV – kontener Node.js z Vite dev server
BUILD – generowanie statycznych plików dist/

Instrukcja dotyczy wyłącznie warstwy frontendowej.

Obejmuje uruchomienie środowiska DEV oraz serwowanie statycznych plików dist/ w środowisku produkcyjnym przez Caddy.

Założenia konfiguracyjne

istnieje kontener Caddy pełniący rolę reverse proxy
istnieje zewnętrzna sieć Docker proxy
aplikacja jest wyłącznie frontendem
Node.js uruchamiany jest tylko w trybach DEV i BUILD
używany obraz: node:24-alpine3.23
domeny:
DEV: dev.apps.fulc.ro
BUILD / przyszły PROD: apps.fulc.ro

Struktura katalogów

Stała struktura katalogów umożliwia rozdzielenie konfiguracji, kodu aplikacji, sekretów oraz danych runtime.

/srv/docker/
  compose/
    mantine/
      compose.yaml
  projects/
    mantine/
      web/
        src/
        public/
        dist/
        package.json
  secrets/
    mantine/
      web/
        app.env
  data/
    mantine/
      web/

Tworzenie katalogów

Tworzymy wymagane katalogi:

sudo mkdir -p /srv/docker/compose/mantine
sudo mkdir -p /srv/docker/projects/mantine/web
sudo mkdir -p /srv/docker/secrets/mantine/web
sudo mkdir -p /srv/docker/data/mantine/web

Nadajemy właściciela bieżącemu użytkownikowi:

sudo chown -R $USER:$USER \
  /srv/docker/compose/mantine \
  /srv/docker/projects/mantine \
  /srv/docker/secrets/mantine \
  /srv/docker/data/mantine

Tworzenie pliku `app.env`

Plik zawiera wyłącznie zmienne frontendowe dostępne w Vite (VITE_*).

micro /srv/docker/secrets/mantine/web/app.env

Zawartość przykładowa:

app.env

VITE_APP_NAME=Mantine Web
VITE_ENV=development

Note

Wszystkie zmienne VITE_* trafiają do bundle JS. Nie przechowujemy tu sekretów.

Scaffold aplikacji Vite

Scaffold wykonywany jest jednorazowo w tymczasowym kontenerze Node.js (docker run --rm), bez instalowania Node na hoście i bez użycia docker compose.

Generujemy aplikację React + TypeScript oraz instalujemy zależności. Katalog projektu jest bind-mountem, więc pliki trafiają bezpośrednio do /srv/docker/projects/mantine/web.

scaffold

docker run --rm -t \
  -v /srv/docker/projects/mantine/web:/work \
  -w /work \
  node:24-alpine3.23 sh -lc '
    set -e
    export CI=1
    export npm_config_yes=true

    yes No | npm create vite@latest . -- --template react-ts

    npm install
    npm install @mantine/core @mantine/hooks @mantine/notifications @emotion/react
  '

Usuwanie node_modules

Podczas npm install katalog node_modules tworzony jest na hoście (bind-mount). Po zakończeniu scaffoldu usuwamy go:

sudo rm -rf /srv/docker/projects/mantine/web/node_modules

Konfiguracja Vite (DEV)

Jawne dopuszczenie domeny DEV jest wymagane przy pracy za reverse proxy.

Edytujemy plik:

micro /srv/docker/projects/mantine/web/vite.config.ts

Zawartość:

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    host: true,
    port: 5173,
    strictPort: true,
    allowedHosts: ['dev.apps.fulc.ro'],
  },
})

Brak allowedHosts powoduje błąd 403 Blocked request za reverse proxy.

Konfiguracja Docker Compose (DEV)

Plik Compose definiuje kontener DEV, mount kodu aplikacji, wolumen node_modules oraz dostęp do sieci proxy.

micro /srv/docker/compose/mantine/compose.yaml

compose.yaml

services:
  mantine-web:
    image: node:24-alpine3.23
    container_name: mantine-web
    working_dir: /app

    environment:
      NODE_ENV: development

    env_file:
      - /srv/docker/secrets/mantine/web/app.env

    volumes:
      - /srv/docker/projects/mantine/web:/app:rw
      - mantine_web_node_modules:/app/node_modules

    command: >
      sh -lc "
        set -e
        npm install
        npm run dev -- --host 0.0.0.0
      "

    networks:
      - proxy

    restart: unless-stopped

volumes:
  mantine_web_node_modules:
    name: mantine_web_node_modules

networks:
  proxy:
    external: true

Uruchomienie środowiska DEV

Uruchamiamy kontener:

cd /srv/docker/compose/mantine
docker compose up -d

Aplikacja dostępna jest pod adresem:

https://dev.apps.fulc.ro

Build aplikacji (BUILD)

Build generuje statyczne pliki frontendowe do katalogu dist/.

docker compose exec mantine-web npm run build

Pliki wynikowe znajdują się w:

/srv/docker/projects/mantine/web/dist

Katalog dist/:

nie jest wersjonowany w Git
stanowi artefakt builda do użycia w środowisku produkcyjnym

Konfiguracja Caddy (DEV + BUILD)

Caddy odpowiada za wystawienie aplikacji frontendowej w obu trybach:

DEV – reverse proxy do Vite dev server (Node.js)
BUILD – serwowanie statycznych plików dist/ bez użycia Node.js

Edytujemy plik Caddyfile:

micro /srv/docker/compose/caddy/Caddyfile

Dodajemy konfigurację:

Caddyfile

apps.fulc.ro {
  root * /srv/docker/projects/mantine/web/dist
  file_server
}

dev.apps.fulc.ro {
  reverse_proxy mantine-web:5173
}

Przeładowujemy konfigurację Caddy:

docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile

Test działania

Sprawdzamy zawartość katalogu dist/:

ls -la /srv/docker/projects/mantine/web/dist

Uwagi utrzymaniowe

instrukcja obejmuje tryby DEV oraz BUILD/PROD
brak backendu, API oraz bazy danych
Node.js używany wyłącznie w DEV i BUILD
środowisko PROD serwuje statyczne pliki dist/ przez Caddy
środowisko DEV charakteryzuje się minimalnym zużyciem zasobów