Getting Started — Developer Machine Setup¶

This document walks through bootstrapping a clean developer machine to the point where you can run someli-api locally, hit /health, log in, and exercise the basic flows.

If you're standing up a new server environment (dev / staging / production), see first-deployment.md instead.

[VERIFY] markers in this document indicate places where the codebase doesn't fully tell the answer and the team needs to confirm. Fill them in once and they're done forever.

1. Prerequisites¶

Operating system¶

Tested on: - Linux (Ubuntu 22.04+, Fedora 40+, Debian 12+) — primary target, matches production - macOS (12+ on Intel or Apple Silicon) — works fine; some native module installs are slower

[VERIFY] Windows / WSL2 status — does the team support Windows directly, or only via WSL2? Polotno / Puppeteer Chromium support is the typical sticking point.

System packages¶

Required for Sharp (image processing) and Puppeteer/Polotno (Chromium):

Ubuntu / Debian:

sudo apt-get update
sudo apt-get install -y \
  build-essential python3 \
  libnss3 libexpat1 fontconfig libatk1.0-0 libatk-bridge2.0-0 \
  libcups2 libdrm2 libgbm1 libgtk-3-0 libxss1 libasound2t64 \
  libpangocairo-1.0-0 libxcomposite1 libxdamage1 libxrandr2 \
  libxtst6 ca-certificates fonts-liberation

Fedora / RHEL:

sudo dnf install -y \
  gcc gcc-c++ make python3 \
  nss expat fontconfig atk at-spi2-atk \
  cups-libs libdrm libgbm gtk3 libXScrnSaver alsa-lib \
  pango libXcomposite libXdamage libXrandr \
  libXtst ca-certificates liberation-fonts

macOS:

brew install pkg-config
# Sharp and Puppeteer have prebuilt darwin binaries; no extra system deps needed

Tools¶

Git — any modern version
NVM (install instructions) — used to manage Node.js versions
A MySQL client of your choice (CLI, TablePlus, DBeaver, MySQL Workbench)

2. Repository¶

git clone https://github.com/Someli-ai/someli-api.git
cd someli-api

Branches: - dev_api — active development; what you'll usually work from - uat_api — UAT staging; merges from dev_api - main — production; merges from uat_api

Feature branches conventionally use new/<name>, fix/<name>, dev/<name>, feature/<name>.

3. Node.js¶

Pinned version: 20.18.1 (matches the Dockerfile base image).

nvm install 20.18.1
nvm use 20.18.1
node --version    # should print v20.18.1

There is no engines field in package.json, so nothing enforces this — but other versions are not tested. Stay on 20.18.1 unless you have a specific reason.

4. Yarn¶

The repo ships its own Yarn 1.22.22 binary in .yarn/releases/. The .yarnrc file points at it. You don't need a separately-installed yarn.

# After cloning, this works without installing yarn globally:
./node_modules/.bin/yarn --version    # only after first install

# Or use the bundled binary directly:
node .yarn/releases/yarn-1.22.22.cjs --version

If you want a global yarn for convenience:

npm install -g yarn@1.22.22

[VERIFY] Yarn version policy — is the team planning to upgrade to Yarn 4 (Berry) or Corepack? If yes, the bundled 1.22.22 path will be retired.

5. Install dependencies¶

yarn install

Expected duration: 5–15 minutes depending on network. The first install pulls Chromium (~150 MB for Puppeteer) and compiles native modules (sharp, etc.).

If install fails¶

Symptom	Fix
`sharp` install errors with libvips messages	Reinstall system deps from §1; `rm -rf node_modules && yarn install`
`puppeteer` Chromium download times out	Re-run install (it resumes), or set `PUPPETEER_SKIP_DOWNLOAD=true` and use a system Chromium with `PUPPETEER_EXECUTABLE_PATH`
Native build fails on macOS Apple Silicon	Make sure Xcode Command Line Tools are installed: `xcode-select --install`
`node-gyp` errors complaining about Python	Install `python3` and ensure it's in PATH

6. MySQL¶

You need a MySQL 8 server reachable from your machine. Three options:

Option A — Local Docker MySQL (recommended for new joiners)¶

docker run --name someli-mysql -d \
  -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=rootpw \
  -e MYSQL_DATABASE=someli_dev \
  -e MYSQL_USER=someli \
  -e MYSQL_PASSWORD=devpw \
  mysql:8

This gives you a clean, throwaway MySQL on localhost:3306 with a someli_dev database.

Option B — Native MySQL install¶

Install MySQL 8 via your OS package manager. Create a database and user:

CREATE DATABASE someli_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'someli'@'localhost' IDENTIFIED BY 'devpw';
GRANT ALL PRIVILEGES ON someli_dev.* TO 'someli'@'localhost';
FLUSH PRIVILEGES;

Option C — Shared dev RDS¶

[VERIFY] Shared dev RDS — is there a shared development RDS instance the team uses? If yes: hostname, security-group rules to allow your IP, and credentials should be documented here.

7. Database schema bootstrap¶

This is currently a manual process. There is no migration tool in the codebase. The schema lives only as the live database; new joiners typically dump from an existing dev DB.

Workflow today:

# Get a schema dump from an existing dev DB
mysqldump --no-data \
  -h <existing-dev-host> -u <user> -p <existing-db> \
  > schema.sql

# Apply to your local DB
mysql -h localhost -u someli -p someli_dev < schema.sql

[VERIFY] Canonical schema source — where does the team consider the "source of truth" schema dump to live? Options: - A schema.sql checked into the repo (does not currently exist) - The shared dev RDS, dumped on demand - A Confluence / wiki page with the latest dump

This needs an answer; new joiners cannot bootstrap without it.

[VERIFY] Seed data — is there a small set of seed rows (test user, test account, test brand) that should ship with a dev DB? If yes, document the seed script.

The absence of a migration tool is also a finding in Enterprise Readiness §5.4. Adopting Knex / Prisma Migrate / Flyway is on the roadmap.

8. The `.env` file¶

.env lives in the project root. It's loaded by conf.js via dotenv. It is gitignored and never committed.

For a fresh setup, create .env from a template. The template should be obtained from another team member or the secrets manager — do not share .env files via Slack or email.

[VERIFY] Where is the .env template kept? Options used by other teams: - A .env.example checked in (with placeholder values) - 1Password / AWS Secrets Manager / Doppler - Onboarding email

Recommended: a .env.example in the repo with every key listed and placeholder values. This double as documentation.

Required keys (the minimum set to boot)¶

# Database
host=localhost
user=someli
password=devpw
dbPort=3306
database=someli_dev
connectionLimit=10

# Server
port=5002
NODE_ENV=development

# Auth
JWT_SECRET_KEY=<any-32-char-string-for-dev>
TOKEN_HEADER_KEY=x-access-token

With just these, npm run dev will start, /health will respond, and /db-health will pass.

Required for most flows¶

# AWS — needed for S3 reads/writes and Bedrock AI calls
AWS_ACCESS_KEY=<your-iam-access-key>
AWS_SECRET_ACCESS_KEY=<your-iam-secret>
S3_Bucket_Name=<bucket-name>
S3_Region=us-west-2
S3_Path=<prefix-inside-bucket>
S3_Bucket_Name2=<secondary-bucket>
S3_Region2=us-west-1
S3_Path2=<prefix>
S3_Path_RAG=<prefix-for-rag-docs>

# AWS Bedrock (Claude / Llama / Nova)
AWS_BEDROCK_KEY=<key>
AWS_BEDROCK_SECRET=<secret>
AWS_BEDROCK_REGION=us-east-1
AWS_BEDROCK_MODEL=<default-model-id>

# Google Cloud (Vertex AI, GCS for RAG)
GOOGLE_API_KEY=<gemini-api-key>
CLOUD_PROJECT_ID=<gcp-project>
CLOUD_LOCATION=us-central1
CLOUD_BUCKET_NAME=<gcs-bucket>
GCS_PATH=<prefix>
GCS_SECRET_NAME=<aws-secrets-manager-name-holding-gcp-creds>
DISPLAY_NAME=<vertex-display-name>

Optional in dev (set per feature)¶

# Email — only needed if you're testing email flows
SENDGRID_API_KEY=<sendgrid-key>
FROM=noreply@someli.ai

# Paddle — only needed for billing flows
PADDLE_TEST_API_KEY=<sandbox-key>
PADDLE_TEST_WEBHOOK_KEY=<sandbox-webhook>
PADDLE_TEST_API_DOMAIN=https://sandbox-api.paddle.com
PADDLE_TEST_ENV=sandbox

# OAuth providers — only needed if you're testing the corresponding login flow
GOOGLE_CLIENT_ID=<oauth-client-id>
GOOGLE_CLIENT_SECRET=<oauth-secret>
FACEBOOK_APP_ID=<...>
FACEBOOK_APP_SECRET=<...>
LINKEDIN_CLIENT_ID=<...>
LINKEDIN_CLIENT_SECRET=<...>
GITHUB_CLIENT_ID=<...>
GITHUB_CLIENT_SECRET=<...>
TIKTOK_CLIENT_ID=<...>
TIKTOK_CLIENT_SECRET=<...>
TWITTER_CLIENT_ID=<...>
TWITTER_CLIENT_SECRET=<...>

# Stock images — only if testing image-search
PEXELS_API_KEY=<key>

# Misc
APP_URL=http://localhost:3000      # frontend URL, used in OAuth callbacks
API_URL=http://localhost:5002      # this API's URL, used in callback URLs
NOTIFY_URL=<webhook-target-for-notifications>

For the complete list of all ~72 env vars with descriptions, see Configuration Reference.

[VERIFY] AWS credentials for new joiners — what is the team's process for issuing AWS IAM credentials to a new engineer? Recommended: a dedicated someli-dev-engineer IAM role with read/write to dev S3 buckets and dev DB, no production access.

[VERIFY] GCP service account — same question for Vertex AI / GCS. Currently fetched from AWS Secrets Manager (GCS_SECRET_NAME); new joiners need either their own GCP creds or access to the secret.

9. First successful run¶

Start the server:

npm run dev

(This is just nodemon server.js.)

Expected output (truncated):

🚀 Server listening on port 5002
✅ Database connected

Verify in another terminal:

curl http://localhost:5002/health
# => {"status":"ok","port":5002,"environment":"development","timestamp":"..."}

curl http://localhost:5002/db-health
# => {"status":"ok","db":"connected"}

If both respond, your installation is correct.

10. Background workers (optional in dev)¶

The 100+ background workers in ecosystem.config.js run via PM2. Most local development does not require them running — they're only needed if you're working on a specific worker's behavior or testing the end-to-end content pipeline.

To start the full fleet:

npm install -g pm2
pm2 start ecosystem.config.js
pm2 list                # see all running processes
pm2 logs <name>         # tail one

Caveat: many workers expect external services (Bedrock, Vertex, social platform OAuth) to be configured. Without those env vars, they will start, fail loudly, and retry. This is loud but mostly harmless in dev.

To start just one worker (recommended for development):

node job_send_mail.js

[VERIFY] Which workers are safe to skip in dev? A short list of workers that are noisy / expensive / unnecessary in local development would help — e.g., "don't run the RAG ingestion locally, it'll burn Bedrock budget."

11. Smoke tests for new joiners¶

Manual checks to confirm the install is fully working:

Check	How
Server boots	`npm run dev` produces no errors at startup
`/health` responds	`curl http://localhost:5002/health`
`/db-health` responds	`curl http://localhost:5002/db-health`
MySQL is reachable	`mysql -h localhost -u someli -p someli_dev -e 'SHOW TABLES;'` lists ~140 tables
Login flow works	Hit the registration endpoint, then login, verify a token is issued
S3 reads work (if AWS creds are set)	Trigger an endpoint that fetches an image

[VERIFY] Concrete login example — provide a curl command that exercises registration + login against a fresh dev DB. New joiners should be able to copy-paste it and see "yes, the auth flow works."

12. Common problems and fixes¶

Symptom	Likely cause	Fix
`Error: Cannot find module 'sharp'` after install	Native build failed silently	`rm -rf node_modules && yarn install`; check system deps from §1
Polotno renders crash with "Failed to launch the browser process"	Missing system deps for Chromium	Install the libnss3 / fontconfig / etc. packages from §1
`ER_ACCESS_DENIED_ERROR` on startup	DB credentials wrong or `.env` not loaded	Verify keys are lowercase (`host`, `user`, `password`) — see Security §4.1 caveat
`process.env.user` resolves to your OS username	`.env` not loaded; `user` env var fell back to shell `$USER`	Confirm `.env` is in the project root and `dotenv` finds it
`EADDRINUSE: address already in use :::5002`	Another process is on port 5002	Kill the other process or change `port=` in `.env`
`puppeteer` complains about Chromium not found	Chromium download failed during install	`cd node_modules/puppeteer && node install.js` to retry
Bedrock calls return AccessDeniedException	Bedrock model isn't enabled in your AWS account	Enable model access in the Bedrock console for `us-east-1`
Workers spam errors about missing tables	DB schema not loaded	See §7 — bootstrap the schema
`mysql.createConnection ECONNREFUSED`	MySQL server not running	Start docker container or local MySQL

[VERIFY] Add team-specific gotchas — what tribal-knowledge problems have new joiners hit that aren't covered here?

13. Where to go next¶

Goal	Doc
Understand the codebase architecture	architecture-overview.md
Find a specific endpoint	API-inventory.md
Understand authentication	authentication.md
Understand the content / AI pipeline	content-pipeline.md, agents-and-ai.md, user-specific-ai.md, rag-pipeline.md
Understand the worker fleet	jobs-inventory.md
Understand all env vars	configuration.md
Understand how things deploy	deployment.md
Stand up a brand-new environment	first-deployment.md
Strategy & roadmap	enterprise-readiness.md

14. What to do when this doc is wrong¶

This document was scaffolded from codebase analysis. Several entries are marked [VERIFY] because the codebase doesn't fully tell the answer. If you hit a gap or the instructions don't work:

Note the actual fix.
Update this doc in the same PR.
Remove the [VERIFY] marker once verified.

The doc is most valuable when the team treats it as a living artifact — not a one-time write-up.