Własne aplikacje i fullstack - Dokumentacja Saplo

Saplo ma gotowe stacki w katalogu, ale możesz wdrożyć dowolną aplikację - także taką, której nie ma na liście - przez git push. Możesz też składać aplikacje fullstack z kilku części w jednym Boxie.

Aplikacja spoza katalogu (Twój własny kod)

Trzy drogi, od najprostszej:

Node.js / framework + git - stwórz aplikację typu Node.js (generic) albo dowolny framework (Next, React, Vue...), podłącz repozytorium i rób git push. Saplo buduje i uruchamia Twój kod.
Docker - aplikacja typu Docker. Wrzucasz własny docker-compose.yml, Saplo go uruchamia. Dowolny obraz, dowolny język.
saplo.yaml - plik w repozytorium opisuje build i start (buildpack). Patrz Plik saplo.yaml.

# dowolne repo -> aplikacja na Saplo
saplo init --stack node --name moja-apka
saplo deploy       # wdrożenie; podlaczenie git push konfiguruje się w panelu

Django + React na jednej domenie

W katalogu wybierz Django + React (django-react). Jedna aplikacja udostępnia API pod /api/, panel Django pod /admin/ i React pod /. Odświeżenie podstrony frontendu zwraca index.html. Nie trzeba konfigurować CORS.

Wybierz źródło szkielet, aby dostać działający przykład z /api/health/, albo repo, aby zainstalować własny projekt.
Dla repo podaj adres Git i gałąź, tag lub commit (domyślnie main). Repo musi być dostępne z Boxa; prywatne repo wymaga skonfigurowanego klucza Git.
Backend (domyślnie backend) musi zawierać manage.py ze standardowym os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'projekt.settings') oraz requirements.txt. Zależności muszą obsługiwać Django poniżej wersji 6. Ustawienia i połączenie z własną bazą przygotuj w projekcie; szkielet korzysta z SQLite.
Frontend (domyślnie frontend) musi zawierać package.json i zgodny package-lock.json. Instalacja wykonuje npm ci oraz komendę builda (domyślnie npm run build). Katalog wyniku to dist dla Vite lub build dla Create React App. Używaj ścieżek zasobów od /, a API wywołuj jako /api/....

Build jest kopiowany do puli zbieranej przez collectstatic. Gunicorn i WhiteNoise obsługują ruch na jednym porcie. Node 20 lub 22 służy wyłącznie do builda i jest instalowany osobno dla aplikacji. Python 3.11 lub 3.12 jest wybierany, jeśli dostępny w Boxie; w przeciwnym razie używany jest systemowy Python, tak jak w recepturze Django.

Ścieżki kodu, faktyczne wersje runtime i polecenie restartu znajdziesz w DJANGO-REACT-SETUP.txt. Receptura nie tworzy superusera; plik zawiera polecenie jego utworzenia. Po zmianach frontendu powtórz build, kopiowanie i collectstatic, a następnie restart. Ta receptura nie konfiguruje automatycznego wdrażania po pushu ani serwowania plików przesłanych przez użytkowników.

Inne aplikacje fullstack (frontend + backend)

Fullstack (np. Next.js + Django, Next.js + WordPress headless) to po prostu dwie aplikacje w tym samym Boxie, każda z własną subdomeną. Spinasz je zmienną środowiskową:

Postaw backend (np. Django jako aplikacja typu Docker) - jeśli potrzebuje bazy, dopisz ją jako kontener we własnym docker-compose.yml.
Postaw frontend (np. Next.js).
Na frontendzie ustaw zmienną wskazującą URL backendu:

saplo env set NEXT_PUBLIC_API_URL=https://moj-backend.saploapp.pl --app moj-frontend

Frontend woła backend po jego publicznym URL. Dla WordPress headless to samo: stawiasz WP, a frontend (Next/Nuxt) czyta jego REST API albo GraphQL.

Fullstack przez Claude (MCP)

Powiedz Claude'owi: "postaw mi fullstack: Django z Postgresem jako backend i Next.js jako frontend, spięte". Claude wykona kroki: postawi backend jako aplikację Docker z Postgresem w docker-compose.yml, ustawi DATABASE_URL, postawi frontend i ustawi zmienną z adresem backendu. Wzorzec jest opisany w samym narzędziu MCP saplo_create_app.

Jak działają szablony katalogu (zaawansowane)

Każdy stack w katalogu to przepis - folder z dwoma plikami:

manifest.toml - deklaracja: nazwa, runtime (php/node/python), czy wystawia port, czy potrzebuje bazy/domeny, opcje konfiguracyjne (np. wybór wersji PHP), a dla baz sekcja [service].
install.sh - skrypt instalacyjny uruchamiany w Boxie (jako root). Dostaje zmienne SAPLO_APP_DIR, SAPLO_DOMAIN, SAPLO_PORT, SAPLO_DB_* i buduje aplikację.

# manifest.toml (skrot)
[module]
id = "react"
name = "React"

[runtime]
needs = ["node", "nginx"]
exposes_port = 0        # 0 = statyczny (nginx serwuje build), >0 = proces na porcie

[needs]
domain = true

Silnik na podstawie manifestu sam ustawia nginx (statyczny / proxy na port / php-fpm), domenę, SSL i pulę zasobów. Tworzenie własnych przepisów oraz katalog społecznościowy to kierunek na kolejne wydania - jeśli chcesz dorzucić stack, napisz do nas.

Wszystkie części fullstacka są w jednym Boxie i mogą gadać po localhost (frontend → backend → baza), a publicznie wystawiasz tyle subdomen, ile chcesz.