Architecture
bullstudio consists of four core services:
| Service | Description | Default Port |
|---|
| Web | Next.js application (UI + API) | 3000 |
| Workers | Background job processing (alerts, etc.) | - |
| Postgres | Primary database | 5432 |
| Redis | Queue backend & caching | 6379 |
Prerequisites
- Node.js >= 20
- pnpm 10.4+
- Docker & Docker Compose
- A Resend account (for transactional emails)
1. Clone & Install
git clone https://github.com/emirce/bullstudio.git
cd bullstudio
pnpm install
2. Start Infrastructure
Start Postgres and Redis via Docker:
docker compose -f docker/dev/compose.yml up -d
- Postgres 16 on
localhost:5432 (user: bullstudio_user, password: bullstudio_password, db: bullstudio_db)
- Redis 7 on
localhost:6379
3. Environment Variables
Copy the example env file and fill in the required values:
| Variable | Required | Description |
|---|
DATABASE_URL | Yes | Postgres connection string |
DIRECT_URL | Yes | Direct Postgres connection (same as DATABASE_URL locally) |
AUTH_SECRET | Yes | Random secret for NextAuth (openssl rand -base64 32) |
ENCRYPTION_KEY | Yes | 32-byte hex key for encrypting Redis credentials (openssl rand -hex 32) |
RESEND_API_KEY | Yes | API key from Resend |
AUTH_GOOGLE_ID | No | Google OAuth client ID |
AUTH_GOOGLE_SECRET | No | Google OAuth client secret |
AUTH_GITHUB_ID | No | GitHub OAuth client ID |
AUTH_GITHUB_SECRET | No | GitHub OAuth client secret |
.env for local development:
DATABASE_URL="postgresql://bullstudio_user:bullstudio_password@localhost:5432/bullstudio_db"
DIRECT_URL="postgresql://bullstudio_user:bullstudio_password@localhost:5432/bullstudio_db"
AUTH_SECRET="your-random-secret-here"
ENCRYPTION_KEY="your-64-char-hex-key-here"
RESEND_API_KEY="re_your_resend_key"
- Use
openssl rand -base64 32 to generate AUTH_SECRET
- Use
openssl rand -hex 32 to generate ENCRYPTION_KEY
4. Prisma Setup
Generate the Prisma client and run migrations:
# Generate the Prisma client
pnpm prisma:generate
# Run database migrations
pnpm prisma:migrate-dev
prisma:generate must run before the dev server starts. The turbo pipeline handles this automatically when running pnpm dev.
5. Start Development
This starts the web app at http://localhost:3000 with hot-reload enabled.
To run workers separately:
Resend Setup
bullstudio uses Resend for transactional emails (invitations, alerts, etc.).
- Create a free account at resend.com
- Add and verify your domain (or use the sandbox domain for development)
- Generate an API key and add it to your
.env as RESEND_API_KEY
Without a valid Resend API key, email features (team invitations, alert notifications) will not work.
