exKey

Monorepo contenant l'API et l'interface admin du projet exKey.

exkey/
├── apps/
│   ├── api/      # NestJS 11 (Swagger, Drizzle ORM, PostgreSQL)
│   └── admin/    # SvelteKit 2 + Svelte 5 (adapter-node)
├── .forgejo/     # workflows CI Forgejo Actions
└── docker-compose.yml

Prerequis

• Node 22 LTS (ou superieur)
• pnpm 10 (corepack enable && corepack prepare pnpm@10.4.1 --activate)
• PostgreSQL 18 local pour le mode dev (ou Docker uniquement)
• Docker + Docker Compose v2 pour la stack complete

Quickstart — mode dev natif (Postgres local)

1. Sur ton PostgreSQL local, cree le user et la base :

   CREATE USER exkey WITH PASSWORD 'exkey';
   CREATE DATABASE exkey OWNER exkey;
   

2. Installe les dependances depuis la racine :

   pnpm install
   

3. Copie les fichiers d'environnement :

   cp apps/api/.env.example apps/api/.env
   cp apps/admin/.env.example apps/admin/.env
   

4. (Premiere fois uniquement) genere et applique les migrations :

   pnpm db:generate
   pnpm db:migrate
   

5. Lance API + Admin en parallele :

   pnpm dev
   

URLs disponibles :

• API : http://localhost:3000
• Swagger : http://localhost:3000/docs
• Ping : http://localhost:3000/ping
• Admin : http://localhost:5173

Quickstart — stack complete via Docker Compose

docker compose up --build

Cela demarre 3 conteneurs :

• exkey-db — PostgreSQL 18 (port hote 5433 pour ne pas entrer en conflit avec ton Postgres local)
• exkey-api — NestJS sur 3000
• exkey-admin — SvelteKit sur 5173

Pour personnaliser les ports / credentials, copie .env.example en .env a la racine.

Scripts racine

Commande	Description
pnpm dev	Lance API + Admin en watch (parallele)
pnpm build	Build toutes les apps
pnpm lint	Lint toutes les apps
pnpm test	Tests toutes les apps
pnpm db:generate	Genere une migration Drizzle depuis src/db/schema.ts
pnpm db:migrate	Applique les migrations en attente
pnpm compose:up	Build + demarre la stack Docker
pnpm compose:down	Arrete la stack Docker

Stack technique

• API : NestJS 11, TypeScript, Swagger (OpenAPI 3), Drizzle ORM, driver postgres (postgres.js), validation Zod
• Admin : SvelteKit 2, Svelte 5 (runes), adapter-node, Vite 6
• BDD : PostgreSQL 18
• Build : pnpm workspaces, Docker multi-stage avec cache pnpm
• CI/CD : Forgejo Actions (lint + build + push registre OCI Forgejo)

Variables d'environnement

apps/api/.env

NODE_ENV=development
PORT=3000
DATABASE_URL=postgres://exkey:exkey@localhost:5432/exkey

apps/admin/.env

PUBLIC_API_URL=http://localhost:3000

.env racine (consomme par docker-compose)

POSTGRES_USER=exkey
POSTGRES_PASSWORD=exkey
POSTGRES_DB=exkey
POSTGRES_HOST_PORT=5433
API_HOST_PORT=3000
ADMIN_HOST_PORT=5173

CI Forgejo

Le workflow .forgejo/workflows/ci.yml tourne sur un runner self-hosted labelise runner09 (runs-on: runner09).

Declencheurs et etapes

• PR vers main : pnpm install + pnpm -r build (pas de push d'image).
• Push sur main : lint/build, puis build + push des deux images Docker.
• Release publiee (release: { types: [published] }) : lint/build, puis build + push des deux images Docker.

Strategie de tags Docker

Evenement	Tags pousses sur exkey-api et exkey-admin
push sur main (commit simple)	dev
release publiee (tag ex. v1.2.3)	latest et v1.2.3 (le nom du tag de release)

Concretement :

• Un commit sur main ecrase l'image :dev => image "rolling" de la branche principale.
• Une release ecrase :latest (= derniere version stable) et publie egalement une image immuable taguee avec la version (:v1.2.3), pour pouvoir revenir en arriere ou epingler precisement une version en prod.

Secrets/variables a definir dans Forgejo

• vars.FORGEJO_REGISTRY — ex : forgejo.example.com
• vars.FORGEJO_OWNER — ex : exkey
• secrets.FORGEJO_USERNAME
• secrets.FORGEJO_TOKEN

Le runner Forgejo doit etre demarre avec le label runner09 (option --labels runner09:docker ou equivalent dans config.yml) et supporter l'execution de jobs en container (node:22-alpine est utilise pour le job de lint/build).

Hors-scope (pour l'instant)

• Pas de table metier dans le schema Drizzle (juste un schema vide pret a recevoir des tables)
• Pas d'authentification, CORS permissif
• Pas de tests ecrits
• Pas de packages/shared (a extraire plus tard si besoin)