@kevinmarrec/create-app 0.9.0 → 0.10.1

package/README.md

@@ -19,3 +19,5 @@ bun create @kevinmarrec/app
 # OR
 bunx @kevinmarrec/create-app
 ```
+
+After scaffolding, see the generated `README.md` in your project root for detailed setup instructions, including environment configuration, Docker setup, and development workflows.

package/dist/index.js

@@ -8,7 +8,7 @@ import { x } from "tinyexec";
 import fs from "node:fs/promises";
 
 //#region package.json
-var version = "0.9.0";
+var version = "0.10.1";
 
 //#endregion
 //#region src/utils/fs.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kevinmarrec/create-app",
   "type": "module",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "packageManager": "bun@1.3.2",
   "description": "CLI that scaffolds an opinionated Bun & Vue fullstack application.",
   "author": "Kevin Marrec <kevin@marrec.io>",
@@ -65,6 +65,6 @@
     "tsdown": "^0.16.4",
     "typescript": "^5.9.3",
     "vitest": "^4.0.9",
-    "vue-tsc": "^3.1.3"
+    "vue-tsc": "^3.1.4"
   }
 }

package/template/.docker/traefik/bin/install_cert

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+set -e
+
+CERTS_DIR="$(cd "$(dirname "$0")/../certs" && pwd)"
+
+if ! command -v mkcert >/dev/null 2>&1; then
+  echo "Error: mkcert is not installed." >&2
+  echo "Please install mkcert before running this script." >&2
+  echo "See https://github.com/FiloSottile/mkcert#installation for installation instructions." >&2
+  exit 1
+fi
+
+mkdir -p "$CERTS_DIR"
+
+mkcert -install 2> /dev/null
+
+mkcert -cert-file "$CERTS_DIR/dev.localhost.crt" -key-file "$CERTS_DIR/dev.localhost.key" "dev.localhost" "*.dev.localhost"

package/template/.docker/traefik/bin/uninstall_cert

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -e
+
+CERTS_DIR="$(cd "$(dirname "$0")/../certs" && pwd)"
+
+mkcert -uninstall 2> /dev/null || true
+
+rm -f "$CERTS_DIR"/*.crt "$CERTS_DIR"/*.key 2> /dev/null || true

package/template/.github/scripts/build-stats.md.ts

@@ -7,47 +7,23 @@ import { filesize } from 'filesize'
 import { x } from 'tinyexec'
 import { glob } from 'tinyglobby'
 
-interface FileStats {
-  file: string
-  size: number
-}
-
 async function getFileStats(directory: string) {
-  const fileStats: FileStats[] = []
-
-  for (const file of await glob(['**/*'], { cwd: directory })) {
-    const size = fs.statSync(path.join(directory, file)).size
-    fileStats.push({
+  const fileStats = await Promise.all(
+    (await glob(['**/*'], { cwd: directory })).map(async file => ({
       file,
-      size,
-    })
-  }
+      size: fs.statSync(path.join(directory, file)).size,
+    })),
+  )
 
   fileStats.sort((a, b) => {
-    // Sort so that files starting with 'assets/' come first
-    if (a.file.startsWith('assets/') && !b.file.startsWith('assets/')) return -1
-    if (!a.file.startsWith('assets/') && b.file.startsWith('assets/')) return 1
-
-    // Within that, files ending with '.js' come first
-    if (a.file.endsWith('.js') && !b.file.endsWith('.js')) return -1
-    if (!a.file.endsWith('.js') && b.file.endsWith('.js')) return 1
-
-    // Otherwise sort alphabetically
-    return a.file.localeCompare(b.file)
+    const scoreA = (a.file.startsWith('assets/') ? 2 : 0) + (a.file.endsWith('.js') ? 1 : 0)
+    const scoreB = (b.file.startsWith('assets/') ? 2 : 0) + (b.file.endsWith('.js') ? 1 : 0)
+    return scoreB - scoreA || a.file.localeCompare(b.file)
   })
 
   return fileStats
 }
 
-async function generateFileStatsMarkdown(directory: string) {
-  const fileStats = await getFileStats(directory)
-  return [
-    '| File | Size |',
-    '| :--- | ---: |',
-    ...fileStats.map(file => `| ${file.file} | ${filesize(file.size)} |`),
-  ].join('\n')
-}
-
 async function main() {
   const { positionals: [directory] } = parseArgs({
     args: process.argv.slice(2),
@@ -61,7 +37,12 @@ async function main() {
 
   await x('bun', ['run', 'build'], { nodeOptions: { cwd: directory } })
 
-  const markdownTable = await generateFileStatsMarkdown(path.join(directory, 'dist'))
+  const fileStats = await getFileStats(path.join(directory, 'dist'))
+  const markdownTable = [
+    '| File | Size |',
+    '| :--- | ---: |',
+    ...fileStats.map(file => `| ${file.file} | ${filesize(file.size)} |`),
+  ].join('\n')
   process.stdout.write(`${markdownTable}\n`)
 }
 

package/template/README.md

@@ -0,0 +1,330 @@
+# Project Template
+
+A full-stack application template with a Vue.js frontend, Bun-based API backend, PostgreSQL database, and Docker Compose setup for local development.
+
+## Overview
+
+This template provides a modern full-stack application structure with:
+
+- **Frontend (app)**: Vue 3 application with Vite, UnoCSS, TypeScript, and TanStack Query
+- **Backend (api)**: Bun-based API server with oRPC, Better Auth, and Drizzle ORM
+- **Database**: PostgreSQL with Drizzle migrations
+- **Infrastructure**: Docker Compose with Traefik reverse proxy, PostgreSQL, and Metabase
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) (v1.3 or later)
+- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/)
+- [Node.js LTS](https://nodejs.org/en/download/) (for compatibility)
+- [mkcert](https://github.com/FiloSottile/mkcert) (for local TLS certificates)
+
+## Project Structure
+
+```
+project/
+├── api/                   # Backend API server
+│   ├── src/
+│   │   ├── auth/            # Authentication setup (Better Auth)
+│   │   ├── database/        # Database schema and migrations (Drizzle)
+│   │   ├── orpc/            # Router definitions (oRPC)
+│   │   ├── env.ts           # Environment variable loading and validation (Valibot)
+│   │   └── main.ts          # API entry point
+│   └── package.json
+├── app/                   # Frontend Vue application
+│   ├── src/
+│   │   ├── components/      # Vue components
+│   │   ├── composables/     # Vue composables (auth, etc.)
+│   │   ├── lib/             # Library utilities (oRPC client)
+│   │   └── main.ts          # App entry point
+│   └── package.json
+├── compose.yaml              # Docker Compose configuration
+└── package.json              # Root workspace configuration
+```
+
+## Getting Started
+
+### 1. Install Dependencies
+
+```bash
+bun install
+```
+
+### 2. Set Up Environment Variables
+
+> **Note**: If `.env.development` (API) or `.env` (App) files already exist in the template, you may skip this step. Otherwise, create them as described below.
+
+#### API Environment Variables
+
+Create a `.env.development` file in the `api/` directory with the following variables:
+
+```bash
+# api/.env.development
+AUTH_SECRET=your-secret-key-here
+DATABASE_URL=postgresql://user:password@postgres:5432/app
+ALLOWED_ORIGINS=https://app.dev.localhost
+LOG_LEVEL=info
+HOST=0.0.0.0
+PORT=4000
+```
+
+**Required variables:**
+
+- `AUTH_SECRET` - Secret key for authentication encryption
+- `DATABASE_URL` - PostgreSQL connection string
+
+**Optional variables:**
+
+- `ALLOWED_ORIGINS` - Comma-separated list of allowed CORS origins (default: empty)
+- `LOG_LEVEL` - Logging level: `fatal`, `error`, `warn`, `info`, `debug`, `trace`, or `silent` (default: `info`)
+- `HOST` - Server host (default: `0.0.0.0`)
+- `PORT` - Server port (default: `4000`)
+
+#### App Environment Variables
+
+Create a `.env` file in the `app/` directory with the following variables:
+
+```bash
+# app/.env
+VITE_API_URL=https://api.dev.localhost
+```
+
+**Required variables:**
+
+- `VITE_API_URL` - API base URL for the frontend
+
+### 3. Set Up Local TLS Certificates
+
+To access the HTTPS URLs (`https://*.dev.localhost`), you need to set up trusted local TLS certificates using [mkcert](https://github.com/FiloSottile/mkcert).
+
+Check their [installation guide](https://github.com/FiloSottile/mkcert#installation) for detailed instructions on installing mkcert.
+
+Then, run the following command to generate the certificates:
+
+```bash
+.docker/traefik/bin/install_cert
+```
+
+This will generate the certificates in `.docker/traefik/certs/` and install the mkcert root CA into your system trust store.
+
+> [!IMPORTANT]
+> If your system is running on WSL and you are using Firefox or Zen Browser, **you must import the mkcert root CA into your browser trust store.**
+>
+> 1. Find the root CA file path:
+>    ```bash
+>    echo "wslpath -w $(mkcert -CAROOT)/rootCA.pem"
+>    # \\wsl.localhost\Ubuntu\home\user\.local\share\mkcert\rootCA.pem
+>    ```
+> 2. Import the root CA file into your browser trust store:
+>    - **Settings** -> **Privacy & Security**.
+>    - **Certificates** -> **View Certificates...**
+>    - **Authorities** tab -> **Import...**
+>    - Select the rootCA.pem file (using the path found above)
+>    - Check **"Trust this CA to identify websites"**
+>    - Click **OK**
+
+### 4. Start Docker Services and Access the Application
+
+Start all services (Traefik, PostgreSQL, Metabase, API, and App):
+
+```bash
+docker compose up -d
+```
+
+Once the services are running, you can access:
+
+- Frontend: https://app.dev.localhost
+- API: https://api.dev.localhost
+- Traefik Dashboard: https://traefik.dev.localhost
+- Metabase: https://metabase.dev.localhost
+
+### 5. Stopping Services
+
+To stop all Docker services:
+
+```bash
+docker compose down
+```
+
+To stop and remove volumes (⚠️ this will delete database data):
+
+```bash
+docker compose down -v
+```
+
+## Development
+
+### Running Services Locally (without Docker)
+
+You can also run the services locally without Docker. Note that you'll still need PostgreSQL running (either locally or via Docker).
+
+#### API Server
+
+```bash
+cd api
+bun run dev
+```
+
+The API will run on `http://localhost:4000` (or the port specified in `PORT`).
+
+#### Frontend App
+
+```bash
+cd app
+bun run dev
+```
+
+The app will run on `http://localhost:5173` (Vite default port).
+
+### Database Management
+
+#### Generate Migrations
+
+After modifying the database schema in `api/src/database/schema/`, generate migrations:
+
+```bash
+cd api
+bun run db:generate
+```
+
+#### Run Migrations
+
+Migrations run automatically when starting the API in dev mode. To run manually:
+
+```bash
+cd api
+bun run db:migrate
+```
+
+## Available Scripts
+
+### Root Level Scripts
+
+- `bun run check` - Run all checks (ESLint, Stylelint, unused dependencies, TypeScript)
+- `bun run lint` - Run linting (ESLint and Stylelint)
+- `bun run lint:inspect` - Open ESLint config inspector
+- `bun run update` - Update dependencies
+
+### API Scripts (`cd api`)
+
+- `bun run dev` - Start development server with hot reload
+- `bun run build` - Build production binary
+- `bun run db:generate` - Generate database migrations
+- `bun run db:migrate` - Run database migrations
+
+### App Scripts (`cd app`)
+
+- `bun run dev` - Start development server with HMR (Hot Module Replacement)
+- `bun run build` - Build for production (static site)
+- `bun run build:analyze` - Build with bundle analyzer
+- `bun run preview` - Preview production build
+
+## Docker Compose Services
+
+### Traefik
+
+Reverse proxy and load balancer that handles:
+
+- HTTPS termination
+- SSL certificate management (requires certificates in `.docker/traefik/certs/`)
+- Routing to services based on hostnames
+- Dashboard accessible at https://traefik.dev.localhost
+
+### PostgreSQL
+
+Database service with:
+
+- Default database: `app`
+- Default user: `user`
+- Default password: `password`
+- Port: `5432`
+- Persistent volume: `postgres_data`
+
+### Metabase
+
+Business intelligence tool for data visualization and analytics with:
+
+- Persistent volume: `metabase_data`
+- Accessible via Traefik at https://metabase.dev.localhost (runs on port `3000` internally)
+
+### API
+
+Backend API service running Bun with:
+
+- Hot reload enabled
+- Automatic database migrations on startup
+- Health check endpoint: `/health`
+- Auth endpoints: `/auth/*`
+- RPC endpoints: `/rpc/*`
+- Accessible via Traefik at https://api.dev.localhost (runs on port `4000` internally)
+
+### App
+
+Frontend Vue application with:
+
+- Vite dev server
+- Hot module replacement
+- Accessible via Traefik at https://app.dev.localhost (runs on port `5173` internally)
+
+## Environment Variables
+
+For detailed environment variable setup, see [Set Up Environment Variables](#2-set-up-environment-variables) in the Getting Started section.
+
+**Quick reference:**
+
+- **API** (`.env.development`): `AUTH_SECRET` (required), `DATABASE_URL` (required), `ALLOWED_ORIGINS`, `LOG_LEVEL`, `HOST`, `PORT`
+- **App** (`.env`): `VITE_API_URL` (required)
+
+## Building for Production
+
+### Build API
+
+```bash
+cd api
+bun run build
+```
+
+This creates a compiled binary at `api/dist/api`.
+
+### Build App
+
+```bash
+cd app
+bun run build
+```
+
+This creates a static site in `app/dist/`.
+
+## Troubleshooting
+
+### Port Already in Use
+
+If ports 80, 443, or 5432 are already in use, modify the port mappings in `compose.yaml`.
+
+### SSL Certificate Warnings
+
+If you see SSL certificate warnings when accessing `https://*.dev.localhost` URLs, ensure you have completed the [Local TLS Setup](#3-set-up-local-tls-certificates) to generate trusted certificates using mkcert.
+
+**Note**: Without proper certificates, Traefik may fail to start or services may not be accessible via HTTPS.
+
+### Service Logs
+
+To view logs for a specific service:
+
+```bash
+docker compose logs -f <service-name>
+```
+
+For example:
+
+- `docker compose logs -f api` - View API logs
+- `docker compose logs -f app` - View app logs
+- `docker compose logs -f traefik` - View Traefik logs
+
+## Tech Stack
+
+- **Runtime**: Bun
+- **Language**: TypeScript
+- **Frontend**: Vue 3, Vite, UnoCSS, TanStack Query
+- **Backend**: Bun, oRPC, Better Auth, Drizzle ORM
+- **Database**: PostgreSQL
+- **Infrastructure**: Docker Compose, Traefik

package/template/api/.env.development

@@ -1,4 +1,4 @@
-ALLOWED_ORIGINS=https://app.dev.localhost
-AUTH_SECRET=foo
-DATABASE_URL=.db
-NODE_ENV=development
+ALLOWED_ORIGINS="https://app.dev.localhost"
+AUTH_SECRET="D0QykrmzDgVrP4GCKkFPT1CB1UplFk4bhIJk92SUtSQ="
+DATABASE_URL="postgresql://user:password@postgres:5432/app"
+NODE_ENV="development"

package/template/api/package.json

@@ -3,12 +3,13 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "dev": "bun --watch --no-clear-screen src/main.ts | pino-pretty",
+    "dev": "bun run db:migrate 1> /dev/null && bun --watch --no-clear-screen src/main.ts | pino-pretty",
     "build": "bun build src/main.ts --compile --minify --sourcemap --outfile dist/api",
     "db:generate": "bun --bun run drizzle-kit generate --config src/database/drizzle/config.ts",
     "db:migrate": "bun --bun run drizzle-kit migrate --config src/database/drizzle/config.ts"
   },
   "dependencies": {
+    "@libsql/client": "^0.15.15",
     "@orpc/server": "^1.11.2",
     "better-auth": "^1.3.34",
     "drizzle-orm": "^0.44.7",
@@ -16,9 +17,9 @@
     "valibot": "^1.1.0"
   },
   "devDependencies": {
-    "@electric-sql/pglite": "^0.3.14",
     "@types/bun": "^1.3.2",
     "drizzle-kit": "^0.31.7",
+    "pg": "^8.16.3",
     "pino-pretty": "^13.1.2"
   }
 }

package/template/api/src/auth/index.ts

@@ -2,10 +2,13 @@ import { betterAuth } from 'better-auth'
 import { type DB, drizzleAdapter } from 'better-auth/adapters/drizzle'
 import type { BaseLogger } from 'pino'
 
+import { env } from '../env'
+
 export function createBetterAuth({ db, logger }: { db: DB, logger: BaseLogger }) {
   return betterAuth({
     basePath: '/auth',
-    trustedOrigins: import.meta.env.ALLOWED_ORIGINS.split(','),
+    secret: env.auth.secret,
+    trustedOrigins: env.cors.allowedOrigins,
     database: drizzleAdapter(db, {
       provider: 'pg',
       usePlural: true,

package/template/api/src/database/drizzle/config.ts

@@ -1,10 +1,11 @@
 import { defineConfig } from 'drizzle-kit'
 
+import { env } from '../../env'
+
 export default defineConfig({
   casing: 'snake_case',
   dialect: 'postgresql',
-  driver: 'pglite',
-  dbCredentials: { url: import.meta.env.DATABASE_URL },
+  dbCredentials: { url: env.database.url },
   schema: 'src/database/schema',
   out: 'src/database/migrations',
 })

package/template/api/src/database/index.ts

@@ -1,11 +1,13 @@
-import { PGlite } from '@electric-sql/pglite'
-import { drizzle } from 'drizzle-orm/pglite'
+import { drizzle } from 'drizzle-orm/bun-sql'
 
+import { env } from '../env'
 import { logger } from '../utils/logger'
 import * as schema from './schema'
 
 export const db = drizzle({
-  client: new PGlite(import.meta.env.DATABASE_URL),
+  connection: {
+    url: env.database.url,
+  },
   casing: 'snake_case',
   schema,
   logger: {

package/template/api/src/env.ts

@@ -0,0 +1,67 @@
+import * as v from 'valibot'
+
+const schema = v.object({
+  auth: v.object({
+    secret: v.string(),
+  }),
+  cors: v.object({
+    allowedOrigins: v.pipe(
+      v.optional(v.string(), ''),
+      v.transform(input => input.split(',').filter(Boolean)),
+    ),
+  }),
+  database: v.object({
+    url: v.string(),
+  }),
+  log: v.object({
+    level: v.optional(v.union([
+      v.literal('fatal'),
+      v.literal('error'),
+      v.literal('warn'),
+      v.literal('info'),
+      v.literal('debug'),
+      v.literal('trace'),
+      v.literal('silent'),
+    ]), 'info'),
+  }),
+  server: v.object({
+    host: v.optional(v.string(), '0.0.0.0'),
+    port: v.pipe(
+      v.optional(v.string(), '4000'),
+      v.decimal(),
+      v.transform(input => Number(input)),
+    ),
+  }),
+})
+
+const parsed = v.safeParse(schema, {
+  auth: {
+    secret: import.meta.env.AUTH_SECRET,
+  },
+  cors: {
+    allowedOrigins: import.meta.env.ALLOWED_ORIGINS,
+  },
+  database: {
+    url: import.meta.env.DATABASE_URL,
+  },
+  log: {
+    level: import.meta.env.LOG_LEVEL,
+  },
+  server: {
+    host: import.meta.env.HOST,
+    port: import.meta.env.PORT,
+  },
+})
+
+if (!parsed.success) {
+  throw new Error([
+    '🚨 Environment Validation Error!',
+    ...parsed.issues.map(issue =>
+      issue.path
+        ? `[${issue.path.map(p => p.key).join('.')}] ${issue.message}`
+        : issue.message,
+    ),
+  ].join('\n'))
+}
+
+export const env = parsed.output

package/template/api/src/main.ts

@@ -2,6 +2,7 @@ import process from 'node:process'
 
 import { createBetterAuth } from './auth'
 import { db } from './database'
+import { env } from './env'
 import { createRpc } from './orpc'
 import { router } from './orpc/router'
 import { cors } from './utils/cors'
@@ -11,9 +12,10 @@ const auth = createBetterAuth({ db, logger })
 const rpc = createRpc({ auth, db, logger }, router)
 
 const server = Bun.serve({
-  hostname: import.meta.env.HOST ?? '0.0.0.0',
-  port: import.meta.env.PORT ?? 4000,
+  hostname: env.server.host,
+  port: env.server.port,
   routes: {
+    '/health': () => new Response('OK', { status: 200 }),
     '/auth/*': cors(auth.handler),
     '/rpc/*': cors(rpc.handler),
   },

package/template/api/src/utils/cors.ts

@@ -1,10 +1,10 @@
-export function cors(handler: (req: Request) => Promise<Response>) {
-  const allowedOrigins = import.meta.env.ALLOWED_ORIGINS.split(',')
+import { env } from '../env'
 
+export function cors(handler: (req: Request) => Promise<Response>) {
   return async (req: Request) => {
-    const origin = req.headers.get('origin') ?? ''
+    const origin = req.headers.get('origin')
 
-    if (!origin || !allowedOrigins.includes(origin)) {
+    if (origin && !env.cors.allowedOrigins.includes(origin)) {
       return new Response('Origin not allowed', { status: 403 })
     }
 
@@ -19,7 +19,10 @@ export function cors(handler: (req: Request) => Promise<Response>) {
     }
 
     response.headers.append('Access-Control-Allow-Credentials', 'true')
-    response.headers.append('Access-Control-Allow-Origin', origin)
+
+    if (origin) {
+      response.headers.append('Access-Control-Allow-Origin', origin)
+    }
 
     return response
   }

package/template/api/src/utils/logger.ts

@@ -1,7 +1,9 @@
 import pino from 'pino'
 
+import { env } from '../env'
+
 export const logger = pino({
-  level: import.meta.env.LOG_LEVEL ?? 'info',
+  level: env.log.level,
   base: {},
 })
 

package/template/app/index.html

@@ -4,6 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="description" content="Description" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="dark light" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>Title</title>
   </head>

package/template/app/package.json

@@ -12,8 +12,8 @@
     "@kevinmarrec/vue-i18n": "^1.1.3",
     "@orpc/client": "^1.11.2",
     "@orpc/tanstack-query": "1.11.2",
-    "@tanstack/query-core": "^5.90.9",
-    "@tanstack/vue-query": "^5.91.1",
+    "@tanstack/query-core": "^5.90.10",
+    "@tanstack/vue-query": "^5.91.2",
     "@unhead/vue": "^2.0.19",
     "@vueuse/core": "^14.0.0",
     "better-auth": "^1.3.34",

package/template/app/src/lib/orpc.ts

@@ -10,6 +10,7 @@ const link = new RPCLink({
     globalThis.fetch(request, {
       ...init,
       credentials: 'include',
+      signal: AbortSignal.timeout(30_000),
     }),
 })
 

package/template/compose.yaml

@@ -13,8 +13,9 @@ services:
       - no-new-privileges:true
     command:
       # General configuration
-      - --log.level=INFO
       - --api.dashboard=true
+      - --ping=true
+      - --log.level=INFO
       # Entrypoints for HTTP and HTTPS
       - --entrypoints.websecure.address=:443
       - --entrypoints.web.address=:80
@@ -26,24 +27,70 @@ services:
       - --providers.docker.exposedbydefault=false
       - --providers.file.directory=/etc/traefik/dynamic
       - --providers.file.watch=true
+    ports:
+      - 80:80
+      - 443:443
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ./.docker/traefik/dynamic:/etc/traefik/dynamic:ro # Mount the dynamic config directory
+      - ./.docker/traefik/certs:/certs:ro # Mount the certs directory
+    healthcheck:
+      test: [CMD-SHELL, traefik healthcheck --ping]
+      interval: 1s
+      timeout: 1s
+      retries: 10
     labels:
       traefik.enable: 'true'
       traefik.http.routers.traefik.rule: Host(`traefik.dev.localhost`)
       traefik.http.routers.traefik.entrypoints: websecure
       traefik.http.routers.traefik.tls: 'true'
       traefik.http.routers.traefik.service: api@internal
+
+  postgres:
+    image: postgres:18-alpine
+    container_name: postgres
+    environment:
+      - POSTGRES_USER=user
+      - POSTGRES_PASSWORD=password
+      - POSTGRES_DB=app
     ports:
-      - 80:80
-      - 443:443
+      - 5432:5432
     volumes:
-      - /var/run/docker.sock:/var/run/docker.sock:ro
-      - ./.docker/traefik/dynamic:/etc/traefik/dynamic:ro # Mount the dynamic config directory
-      - ./.docker/traefik/certs:/certs:ro # Mount the certs directory
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: [CMD-SHELL, "psql postgresql://user:password@postgres:5432/app -c 'SELECT 1' 2> /dev/null"]
+      interval: 1s
+      timeout: 1s
+      retries: 10
+
+  metabase:
+    image: metabase/metabase:v0.57.x
+    container_name: metabase
+    environment:
+      - MB_DB_TYPE=h2
+      - MB_DB_FILE=/var/lib/metabase/metabase.db
+      - MB_SITE_URL=https://metabase.dev.localhost
+    volumes:
+      - metabase_data:/var/lib/metabase
+    healthcheck:
+      test: [CMD-SHELL, curl -f http://localhost:3000/api/health]
+      interval: 1s
+      timeout: 1s
+      retries: 20
+    labels:
+      traefik.enable: 'true'
+      traefik.http.routers.metabase.rule: Host(`metabase.dev.localhost`)
+      traefik.http.routers.metabase.entrypoints: websecure
+      traefik.http.routers.metabase.tls: 'true'
+      traefik.http.services.metabase.loadbalancer.server.port: '3000'
 
   api:
     <<: *common
     depends_on:
-      - traefik
+      traefik:
+        condition: service_healthy
+      postgres:
+        condition: service_healthy
     container_name: api
     image: oven/bun:1-alpine
     init: true
@@ -73,3 +120,11 @@ services:
       traefik.http.routers.app.entrypoints: websecure
       traefik.http.routers.app.tls: 'true'
       traefik.http.services.app.loadbalancer.server.port: '5173'
+
+networks:
+  default:
+    name: dev
+
+volumes:
+  postgres_data:
+  metabase_data:

package/template/knip.config.ts

@@ -1,7 +1,9 @@
 import type { KnipConfig } from 'knip'
 
+// Required for Knip to pass
 Object.assign(import.meta.env, {
-  DATABASE_URL: 'foo.db',
+  AUTH_SECRET: '',
+  DATABASE_URL: '',
 })
 
 export default {

package/template/package.json

@@ -31,6 +31,6 @@
     "tinyexec": "^1.0.2",
     "tinyglobby": "^0.2.15",
     "typescript": "~5.9.3",
-    "vue-tsc": "^3.1.3"
+    "vue-tsc": "^3.1.4"
   }
 }

package/template/api/src/env.d.ts

@@ -1,11 +0,0 @@
-interface ImportMetaEnv {
-  readonly ALLOWED_ORIGINS: string
-  readonly AUTH_SECRET: string
-  readonly DATABASE_URL: string
-  readonly LOG_LEVEL: string
-  readonly NODE_ENV: string
-}
-
-interface ImportMeta {
-  readonly env: ImportMetaEnv
-}

package/template/docs/local-tls.md

@@ -1,152 +0,0 @@
-# **Local TLS Setup Guide**
-
-This guide provides the essential steps to install mkcert and generate trusted TLS certificates for your Traefik-secured local development environment.
-
-Certificates are expected in `.docker/traefik/certs/`.
-
-## **Prerequisites**
-
-- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed
-- Ports 80 and 443 available on your system
-- Administrator/sudo access for installing mkcert
-
-## **1. Install mkcert (Ubuntu/WSL)**
-
-Download, install, and clean up the executable:
-
-```sh
-curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
-chmod +x mkcert-v*-linux-amd64
-sudo cp mkcert-v*-linux-amd64 /usr/local/bin/mkcert
-rm mkcert-v*-linux-amd64
-```
-
-Verify the installation:
-
-```sh
-mkcert -version
-```
-
-## **2. Install the mkcert Root CA**
-
-Install the local root CA to trust generated certificates:
-
-```sh
-mkcert -install
-```
-
-### **Firefox and Zen Browser (Manual Import)**
-
-Browsers like Firefox and Firefox-based Zen Browser require manual import into their internal trust stores.
-
-1. **Find Root CA File Path:**
-   Run the appropriate command below to get the full path to the rootCA.pem file:
-   - **Linux Native (or WSL for Linux Apps):**
-
-     ```sh
-     echo "$(mkcert -CAROOT)/rootCA.pem"
-     # /home/user/.local/share/mkcert/rootCA.pem
-     ```
-
-   - **WSL for Windows Host Applications:** Use wslpath to get the Windows-formatted path.
-     ```sh
-     wslpath -w "$(mkcert -CAROOT)/rootCA.pem"
-     # \\wsl.localhost\Ubuntu\home\user\.local\share\mkcert\rootCA.pem
-     ```
-
-2. **Import:** In the browser's settings:
-   - **Settings** -> **Privacy & Security**.
-   - **Certificates** -> **View Certificates...**
-   - **Authorities** tab -> **Import...**
-   - Select the rootCA.pem file (using the path found above)
-   - Check **"Trust this CA to identify websites"**
-   - Click **OK**
-
-## **3. Generate the `dev.localhost` Certificate**
-
-Generate the wildcard certificate for `*.dev.localhost` and place the files where Traefik is configured to look (See [`tls.yml`](../.docker/traefik/dynamic/tls.yml)).
-
-1. **Create Directory:**
-
-   ```sh
-   mkdir -p .docker/traefik/certs
-   ```
-
-2. **Generate Certificate:**
-
-   ```sh
-   mkcert \
-     -cert-file .docker/traefik/certs/dev.localhost.crt \
-     -key-file .docker/traefik/certs/dev.localhost.key \
-     "dev.localhost" "*.dev.localhost"
-   ```
-
-3. **Verify Certificate:**
-
-   ```sh
-   openssl x509 -in .docker/traefik/certs/dev.localhost.crt -text -noout | grep -A 2 "Subject Alternative Name"
-   ```
-
-## **4. Validate Setup**
-
-1. **Start Services:**
-
-   ```sh
-   docker compose up -d
-   ```
-
-2. **Test in Browser:**
-
-- Visit **https://traefik.dev.localhost** — you should see the Traefik dashboard
-- Visit **https://app.dev.localhost** — you should see your app
-- Both should load without SSL warnings
-
-## **5. Troubleshooting**
-
-### **Certificate Files Missing**
-
-If Traefik fails to start or shows TLS errors, verify the certificate files exist:
-
-```sh
-ls -la .docker/traefik/certs/
-```
-
-### **Browser Shows SSL Warning**
-
-- Ensure mkcert root CA is installed (`mkcert -install`)
-- For Firefox/Zen Browser, manually import the root CA (see section 2)
-- Clear browser cache and restart the browser
-
-### **Certificate Expiration**
-
-mkcert certificates are valid for a long time, but if you need to regenerate:
-
-1. **Remove old certificates:**
-
-   ```sh
-   rm .docker/traefik/certs/dev.localhost.*
-   ```
-
-2. **Regenerate (see section 3)**
-
-## **6. Clean Up**
-
-1. **Stop Services:**
-
-   ```sh
-   docker compose down
-   ```
-
-2. **Remove Certificates (Optional):**
-
-   ```sh
-   rm -rf .docker/traefik/certs
-   ```
-
-3. **Uninstall mkcert Root CA (Optional):**
-
-   ```sh
-   mkcert -uninstall
-   ```
-
-   > **Note:** Removing the root CA will cause SSL warnings in browsers until you reinstall it or regenerate certificates.