01 — `someli-api` setup¶

You've finished the cross-cutting 00-workstation-setup.md. Now stand up someli-api.

1. Clone¶

cd ~/src/someli
git clone git@github.com:Someli-ai/someli-api.git
cd someli-api
git checkout dev_api          # the active dev branch

Verify with the team if the active dev branch differs.

2. Install dependencies¶

yarn install
# or
npm install

Either works — the lockfile is package-lock.json but the repo has been used with both. First-time install takes ~3–5 minutes because of the native builds (Sharp, Puppeteer, node-canvas).

If yarn install fails with a Chromium / Puppeteer error, you missed a system package — re-read 00-workstation-setup.md §2.

3. The `.env` file¶

The repo does not ship a .env.example. Ask the team for a dev .env. Until you have it, the server cannot start.

The file lives at the project root: someli-api/.env. The application loads it via dotenv from conf.js.

Variables you absolutely need to start the server¶

# Database
host=...              # MySQL host (typically a dev RDS or your local Docker)
user=...              # MySQL user
password=...
database=someli
dbPort=3306
connectionLimit=10

# Server
port=5002
NODE_ENV=development

# JWT / token encryption
JWT_SECRET_KEY=...
TOKEN_HEADER_KEY=Token  # name of the HTTP header carrying the encrypted token

# Session
SESSION_SECRET=change-me

Variables you'll need as soon as you exercise real features¶

Feature	Vars
Email	`SENDGRID_API_KEY`, `FROM`
AWS S3	`AWS_ACCESS_KEY`, `AWS_SECRET_ACCESS_KEY`, `S3_Bucket_Name`, `S3_Region`, `S3_Path`, `S3_Bucket_Name2`, `S3_Region2`, `S3_Path2`, `S3_Bucket_Url2`
Google Cloud (RAG, Vertex AI)	`CLOUD_BUCKET_NAME`, `CLOUD_PROJECT_ID`, `CLOUD_LOCATION`, `GOOGLE_API_KEY`
OpenAI	`OPENAI_API_KEY`
AWS Bedrock (Claude, Llama, Nova)	`AWS_BEDROCK_KEY`, `AWS_BEDROCK_SECRET`, `AWS_BEDROCK_MODEL`, `AWS_BEDROCK_REGION`
Paddle billing	`PADDLE_API_KEY`, `PADDLE_WEBHOOK_KEY`, `PADDLE_API_DOMAIN`, `PADDLE_ENV` (+ `PADDLE_TEST_*` for sandbox)
Social OAuth	`FB_`, `IG_`, `LI_`, `TT_`, `TW_`, `GOOGLE_` — see `../../audit/someli-api/configuration.md` for the full table
Slack notifications	`SLACK_TOKEN`, `SLACK_CHANNEL`
Misc	`IMPACT_*` (in `routes/auth.js`), `PUBLISH_KEY`, `NOTIFY_URL`, `APP_URL`, `API_URL`

Total: ~72 env vars across conf.js (46), dashboard/conf.js (5), and direct process.env.* reads in workers/routes (~21). The full table lives in ../../audit/someli-api/configuration.md.

Junior shortcut. For your first week, request a "developer .env" from the team — pre-populated with non-production secrets for everything. You shouldn't be assembling a 72-variable env file from scratch.

4. Database¶

You need a working MySQL with the Someli schema applied. Three options (in order of preference):

Option A — Connect to the team's shared dev DB¶

Easiest. Get the host / user / password from the team and put them in .env. The schema is already applied; you'll see real-ish dev data.

Option B — Local Docker¶

docker run -d --name someli-mysql \
  -e MYSQL_ROOT_PASSWORD=changeme \
  -e MYSQL_DATABASE=someli \
  -p 3306:3306 \
  mysql:8.0

# Wait ~10 seconds for the server to boot, then load the schema snapshot
# from the audit tree (not from the someli-api repo — the schema isn't committed there):
mysql -h 127.0.0.1 -u root -p someli \
  < ../someli-doc/audit/someli-api/someli-schema.sql

Set .env to point at host=127.0.0.1, user=root, password=changeme.

Option C — Native MySQL install¶

See 00-workstation-setup.md §5.

Watch out: the schema file under someli-doc/ is a snapshot. Verify with the team which migrations have been applied since the snapshot was last refreshed.

5. Start the server¶

yarn start
# or
npm start

Both alias to nodemon server.js — yes, even start uses nodemon. The server boots on port (from .env, default 5002).

You should see:

[server.js] Express listening on 5002
[mysql] connection pool established
[socket.io] listening

If you see Something Went Wrong! — that means modules/dbDriver/lib/mysql.js failed to connect. Re-check your DB env vars.

6. Smoke test¶

curl http://localhost:5002/health
curl http://localhost:5002/db-health

/health returns 200 always. /db-health returns 200 if MySQL is reachable. If both pass, the server is healthy.

7. Auth and the dashboard¶

If you need to hit authenticated endpoints, the easiest path:

Use a known dev user (ask the team for email / password of a seed account).
POST /authenticate (body: email + password) → returns an AES-encrypted token.
Send subsequent requests with the Token header set to that string (header name comes from TOKEN_HEADER_KEY env var).

For analytics / dashboard endpoints, in NODE_ENV=development the auth middleware on dashboard/routes/index.js is bypassed — see ../../audit/someli-api/dashboard-analytics.md.

8. Background jobs (later)¶

You generally do not need to run any job_*.js locally for normal development. The jobs are scheduled via PM2 in production (manifest: ecosystem.config.js). If you do need to run one ad-hoc:

node job_<name>.js

It loads .env via conf.js and connects to MySQL on its own. Don't run any _publish.js job pointed at the production database — they actually post to FB/IG/LI/TT/X.

9. You're done with setup¶

If yarn start succeeds, /health and /db-health return 200, and you can hit /authenticate with a seed user, you are ready.

Next: 02-stack.md.

Troubleshooting¶

Symptom	Likely cause
`Cannot find module '...'` on boot	Re-run `yarn install`; check Node version is 20.x
Sharp / Puppeteer build error	Missing system packages — re-read `00-workstation-setup.md` §2
`Something Went Wrong!` on boot	MySQL not reachable — `mysql -h $host -u $user -p` to test manually
`Error: listen EADDRINUSE :::5002`	Port 5002 collides with `designer-api` or `Someli-admin-api` (they all default to 5002). Set a different `port` in `.env`
Server boots but `/authenticate` returns 500	Likely `JWT_SECRET_KEY` or `TOKEN_HEADER_KEY` missing — set them in `.env`
`S3_Bucket_Name is undefined` at request time	You're hitting a feature that needs S3; set the AWS env vars

01 — someli-api setup¶