160 lines
4.9 KiB
Markdown
160 lines
4.9 KiB
Markdown
# test-app-stack
|
|
|
|
A minimal full-stack reference project:
|
|
|
|
- **Backend** — [ElysiaJS](https://elysiajs.com) running on [Bun](https://bun.sh). Exposes a small JSON API.
|
|
- **Frontend** — [TanStack Start](https://tanstack.com/start) (React 19, SSR via Vite) that calls the backend and renders the result.
|
|
- **Orchestration** — `docker-compose.yml` wiring both services behind an existing [Traefik](https://traefik.io) reverse proxy with automatic Let's Encrypt TLS.
|
|
|
|
```
|
|
test-app-stack/
|
|
├── backend/ # ElysiaJS (Bun)
|
|
│ ├── src/index.ts # API: / /api/health /api/hello
|
|
│ ├── package.json
|
|
│ ├── tsconfig.json
|
|
│ └── Dockerfile
|
|
├── frontend/ # TanStack Start (React, SSR)
|
|
│ ├── src/
|
|
│ │ ├── router.tsx
|
|
│ │ └── routes/
|
|
│ │ ├── __root.tsx # HTML shell
|
|
│ │ └── index.tsx # Home page — fetches /api/hello
|
|
│ ├── vite.config.ts
|
|
│ ├── package.json
|
|
│ ├── tsconfig.json
|
|
│ └── Dockerfile
|
|
├── docker-compose.yml # both services + Traefik labels
|
|
├── .env.example
|
|
└── README.md
|
|
```
|
|
|
|
---
|
|
|
|
## API surface (backend)
|
|
|
|
| Method | Path | Description |
|
|
| ------ | -------------- | --------------------------------------------- |
|
|
| GET | `/` | Service banner / metadata |
|
|
| GET | `/api/health` | Health probe (`{ status: "healthy", ... }`) |
|
|
| GET | `/api/hello` | Demo payload consumed by the frontend |
|
|
|
|
The frontend's home page (`frontend/src/routes/index.tsx`) calls `GET /api/hello`
|
|
against the URL in `VITE_API_URL` and shows the response — this is the
|
|
front ↔ back connection.
|
|
|
|
---
|
|
|
|
## Local development
|
|
|
|
Two terminals.
|
|
|
|
**Backend** (requires [Bun](https://bun.sh)):
|
|
|
|
```bash
|
|
cd backend
|
|
bun install
|
|
bun run dev # http://localhost:3000
|
|
```
|
|
|
|
**Frontend** (requires Node 22+):
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
# point the UI at the local backend
|
|
echo 'VITE_API_URL=http://localhost:3000' > .env
|
|
npm run dev # http://localhost:3000 (use a different port if backend is on 3000)
|
|
```
|
|
|
|
> Both default to port 3000. For local dev run the backend on another port, e.g.
|
|
> `PORT=3001 bun run dev`, and set `VITE_API_URL=http://localhost:3001`.
|
|
|
|
---
|
|
|
|
## Manual build & deploy (Docker + Traefik)
|
|
|
|
This stack does **not** ship its own Traefik. It attaches to the Traefik
|
|
instance and the external `web` Docker network already running on the VPS
|
|
(from the forgejo stack), and reuses its `le` cert resolver.
|
|
|
|
### 1. Prerequisites
|
|
|
|
- Docker + Docker Compose on the host.
|
|
- An existing Traefik container attached to an external network named `web`,
|
|
with a cert resolver named `le` and a `websecure` (:443) entrypoint.
|
|
- **DNS**: create `A` records for both hostnames pointing at the VPS IP:
|
|
- `test-app.emmanuelariasa.com` → frontend
|
|
- `test-app-api.emmanuelariasa.com` → backend
|
|
|
|
(Adjust the names via `.env`. Without DNS, Traefik can't issue certificates.)
|
|
|
|
### 2. Configure
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# edit .env if you want different hostnames / CORS origin
|
|
```
|
|
|
|
### 3. Build the images
|
|
|
|
```bash
|
|
docker compose build
|
|
```
|
|
|
|
`VITE_API_URL` is passed as a build arg to the frontend because Vite inlines it
|
|
into the client bundle at build time — rebuild the frontend if the API hostname
|
|
changes.
|
|
|
|
### 4. Start
|
|
|
|
```bash
|
|
docker compose up -d
|
|
docker compose ps
|
|
docker compose logs -f
|
|
```
|
|
|
|
Traefik picks up the containers via their labels and provisions TLS
|
|
automatically. Once certificates are issued:
|
|
|
|
- Frontend → https://test-app.emmanuelariasa.com
|
|
- Backend → https://test-app-api.emmanuelariasa.com/api/health
|
|
|
|
### 5. Update / redeploy
|
|
|
|
```bash
|
|
git pull
|
|
docker compose build
|
|
docker compose up -d # recreates only changed services
|
|
```
|
|
|
|
### 6. Tear down
|
|
|
|
```bash
|
|
docker compose down # add -v to also drop the app-internal network/volumes
|
|
```
|
|
|
|
---
|
|
|
|
## How the pieces connect
|
|
|
|
```
|
|
Internet ──TLS──▶ Traefik (:443, existing)
|
|
│ Host(test-app.emmanuelariasa.com) → frontend:3000
|
|
│ Host(test-app-api.emmanuelariasa.com) → backend:3000
|
|
▼
|
|
web (external docker network)
|
|
├── frontend (TanStack Start SSR)
|
|
└── backend (ElysiaJS/Bun) ── app-internal ──▶ (future DB)
|
|
```
|
|
|
|
The browser loads the SSR'd frontend, then calls the backend directly over its
|
|
public HTTPS hostname (`VITE_API_URL`). CORS on the backend is restricted to
|
|
`FRONTEND_ORIGIN`.
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- `frontend/src/routeTree.gen.ts` is generated on first `vite dev`/`build` and is git-ignored.
|
|
- Bun lockfile (`bun.lock`) and npm lockfile (`package-lock.json`) are created on first install; commit them for reproducible builds.
|
|
- This repository is intentionally deploy-ready but **not auto-deployed** — run the steps above manually.
|