KKodokod
Back to project

Sloth Board

Documentation

Installation guide, technical stack, and known limitations for Sloth Board.

How to install

[ 02 ]

Clone the repositories

Here are the two repositories: backend_sloth/ and frontend_sloth/.

Terminal
git clone https://github.com/Querelio/backend_slothgit clone https://github.com/Querelio/frontend_sloth

[ 03 ]

Docker Compose and .env

Download docker-compose.yml and .env, place them beside the two folders, then start the containers. DATABASE_URL uses localhost.

  • PostgreSQL listens on port 5432 of the machine.
  • pgAdmin: http://localhost:5050. Email and password: PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD.
Download docker-compose.yml
docker-compose.yml
services:  postgres:    image: postgres:16    restart: unless-stopped    env_file: .env    ports:      - "5432:5432"    volumes:      - pgdata:/var/lib/postgresql/data  pgadmin:    image: dpage/pgadmin4    restart: unless-stopped    env_file: .env    ports:      - "5050:80"    depends_on:      - postgresvolumes:  pgdata:
Download .env
.env
POSTGRES_USER=slothPOSTGRES_PASSWORD=change-mePOSTGRES_DB=slothPGADMIN_DEFAULT_EMAIL=admin@localhostPGADMIN_DEFAULT_PASSWORD=change-me
Terminal
docker compose up -d

Here is the resulting layout.

Project structure
docker-compose.yml
.env
backend_sloth/
├── prisma/
├── src/
├── package.json
└── .env
frontend_sloth/
├── public/
├── src/
├── package.json
└── .env

[ 04 ]

backend_sloth/.env file

Here is backend_sloth/.env. DATABASE_URL reuses the user, password, and database from the Docker .env.

  • Required to start: DATABASE_URL and JWT_SECRET.
  • Default PORT: 3000.
  • Default JWT_EXPIRES_IN: 7d.
  • Default CORS_ORIGIN when empty: http://localhost:5173,http://localhost:4173 (5173 = Vite dev, 4173 = Vite preview). Separate several origins with commas, without extra spaces.
  • SWAGGER_ENABLED: any value other than the string "false" turns Swagger on. Default: on.
Download backend_sloth/.env
backend_sloth/.env
DATABASE_URL="postgresql://sloth:change-me@localhost:5432/sloth"JWT_SECRET="une-longue-chaine-secrete"JWT_EXPIRES_IN=7dPORT=3000CORS_ORIGIN=http://localhost:4173SWAGGER_ENABLED=true

[ 05 ]

Backend: install, migrate, build, start

From backend_sloth/, run the following commands.

  • npm install : Also installs devDependencies. prisma and tsx live there. Do not run npm install --omit=dev before migrations: the Prisma CLI would no longer be available.
  • npx prisma generate : Generates the client in src/generated/prisma. Do this before the build: Nest code imports that client.
  • npx prisma migrate deploy : Applies migrations already committed in prisma/migrations. This is the install and production command. Do not use prisma migrate dev to install: migrate dev is for writing new migrations during development.
  • npx prisma db seed : Reads prisma/seed.ts (declared in prisma.config.ts). Inserts, if missing: the Intervenant role, price modes Heure, Demi-journee, Journee, Forfait, Libre, and statuses Planifiée, Réalisée, Déclarée, Facturée, Réglée. It does not create a user.
  • npm run build : nest build, into the dist/ folder.
  • npm run start:prod : node dist/main.

API: http://localhost:3000. Swagger: http://localhost:3000/docs.

backend_sloth/
npm installnpx prisma generatenpx prisma migrate deploynpx prisma db seednpm run buildnpm run start:prod

[ 06 ]

frontend_sloth/.env file

Here is frontend_sloth/.env. API_URL is read at build time (vite.config.ts: envPrefix = API_). Changing it after npm run build has no effect: you need to rebuild.

Download frontend_sloth/.env
frontend_sloth/.env
API_URL=http://localhost:3000

[ 07 ]

Frontend: install, build, start

From frontend_sloth/, run the following commands.

  • npm run build = tsc -b && vite build, into the dist/ folder.
  • npm run preview serves that dist/ folder.
  • App: http://localhost:4173.
  • If the frontend is not on 4173, set the same origin in the backend CORS_ORIGIN, then restart the backend.
frontend_sloth/
npm installnpm run buildnpm run preview

[ 08 ]

First account

The seed does not create a login. Once the frontend is running, open the app and create the account in the interface, then sign in.

http://localhost:4173

[ 09 ]

Day-to-day order

First install, or after a git pull that touches prisma/

Docker Compose if it is not already running, then the backend, then the frontend.

Terminal
docker compose up -d
backend_sloth/
npm install && npx prisma generate && npx prisma migrate deploy && npx prisma db seed && npm run build && npm run start:prod
frontend_sloth/
npm install && npm run build && npm run preview

Simple restart, schema unchanged

Docker Compose if the database is stopped, then the backend, then the frontend.

Terminal
docker compose up -d
backend_sloth/
npm run start:prod
frontend_sloth/
npm run preview

New schema already migrated in the repository

From backend_sloth/, regenerate the client, apply migrations, then rebuild and restart.

backend_sloth/
npx prisma generatenpx prisma migrate deploynpm run buildnpm run start:prod

Technical stack

A self-hostable full stack application: React frontend, NestJS backend with Prisma, and a PostgreSQL database.

Frontend

  • React
  • Tailwind CSS

Backend

  • NestJS
  • Prisma

Database

  • PostgreSQL

Known limitations

Content coming soon.