Getting Started

Local Installation

Run ShaDo AI on your local machine for development or testing.

Requirements

Tool	Version	Purpose
`Node.js`	≥ 18	Runtime for both backend and frontend
`PostgreSQL`	≥ 14	Primary database
`Redis`	≥ 6	Sessions, rate limiting, refresh tokens
`npm`	≥ 9	Package manager

Option A — Manual Install

If you prefer Docker, skip to Option B — Docker below.

Extract the package

unzip shadoapps-mvp-generator-v1.0.zip
cd shadoapps-mvp-generator-v1.0

Create the database

# macOS / Linux (local postgres)
createdb product_db

# or via psql
sudo -u postgres psql -c "CREATE DATABASE product_db;"
sudo -u postgres psql -c "CREATE USER product_user WITH PASSWORD 'yourpassword';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE product_db TO product_user;"

Configure the backend

cp backend.env.example backend/.env
# Open backend/.env and fill in the required values

Configure the frontend

cp frontend.env.example frontend/.env.local
# Set NEXT_PUBLIC_API_URL=http://localhost:3003

Run the installer

chmod +x install.sh && ./install.sh
# Installs deps, runs Prisma migrations, builds both apps

Start services

chmod +x start.sh && ./start.sh
# Starts shadoapps-backend (port 3003) and shadoapps-frontend (port 3004) via PM2

Open the setup wizard

# Visit in your browser:
http://localhost:3004/setup

Backend .env Reference

Variable	Required	Description
`DATABASE_URL`	✓	PostgreSQL connection string
`REDIS_URL`	✓	Redis URL (default: `redis://localhost:6379`)
`JWT_ACCESS_SECRET`	✓	64-char random string — `openssl rand -hex 64`
`JWT_REFRESH_SECRET`	✓	64-char random string — `openssl rand -hex 64`
`FRONTEND_URL`	✓	Frontend URL for CORS (e.g. `http://localhost:3004`)
`PORT`	—	Backend port (default: `3003`)
`NODE_ENV`	—	`development` or `production`

Generate JWT secrets:

openssl rand -hex 64  # run twice — once for each secret

Option B — Docker

No local Node.js, PostgreSQL, or Redis needed — Docker handles everything.

Requires Docker Desktop (Windows/macOS) or Docker Engine + Compose plugin (Linux).

unzip shadoapps-mvp-generator-v1.0.zip
cd shadoapps-mvp-generator-v1.0
chmod +x docker-setup.sh && ./docker-setup.sh

The script prompts you to fill in secrets, builds images, waits for the database, and prints the app URL.

Useful Docker commands

docker compose logs -f            # tail all logs
docker compose logs -f backend    # backend only
docker compose down               # stop
docker compose down -v            # stop + delete data

PM2 Cheatsheet

pm2 list                     # show running processes
pm2 logs                     # stream all logs
pm2 logs shadoapps-backend   # backend logs only
pm2 restart shadoapps-backend
pm2 stop all