00 — Workstation setup (cross-cutting)¶

Set this up once. After this page, every module just clones into a subdirectory and runs.

If your machine already runs another Someli repo successfully, skim this page and move on — most likely you have everything you need. Come back if a module's per-repo setup throws a native-build or version-mismatch error.

1. Operating system¶

OS	Status	Notes
Linux (Ubuntu 22.04+, Fedora 40+, Debian 12+)	Primary	Matches production. Use this if you can.
macOS 12+ (Intel or Apple Silicon)	Supported	Works fine; native-module installs are slightly slower.
Windows native	Not officially supported	Polotno / Puppeteer Chromium are the typical sticking points.
Windows + WSL2	Works in practice	Treat the WSL2 distro as a Linux machine — install everything there, not on Windows.

Verify with the team if Windows support is required. The platform's deployment OS is Linux on AWS Lightsail; everything is built and tested there.

2. System packages (Linux only — macOS skip)¶

These are required by Sharp (image processing, used by every backend) and Puppeteer/Polotno (Chromium, used by the customer-app FE and both designer halves).

Ubuntu / Debian / WSL2-Ubuntu¶

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.

3. Node.js — install the right version¶

Every backend and frontend uses Node 20.x (production image: node:20.18.3-slim). None of the repos pin the version (no .nvmrc, no .tool-versions, no engines in package.json), so version managers won't auto-switch you. You must set it yourself.

Recommended: use a version manager — nvm (Linux/macOS), fnm, or volta.

# nvm example
nvm install 20.18.3
nvm use 20.18.3
node --version    # should print v20.18.x

Why this matters. Node 22 and Node 18 both appear to work and then fail in subtle ways: native modules (Sharp, Puppeteer) ship prebuilt binaries for specific Node major versions and silently fall back to source compilation otherwise. Stick to 20.x.

4. Package managers¶

You will need both, because different repos use different ones:

Repo	Package manager	Lockfile
`someli-api`	npm or yarn (both work)	`package-lock.json`
`someli-platform`	Yarn 1.x (classic) — do not use npm	`yarn.lock`
`Someli-Designer`	npm	`package-lock.json`
`designer-api`	yarn	`yarn.lock`
`Someli-admin-api`	npm or yarn	`package-lock.json`
`admin_console_R`	npm (multiple lockfiles exist; npm is the canonical one)	`package-lock.json`

Install Yarn 1.x (classic)¶

# After Node is installed:
npm install --global yarn
yarn --version    # MUST be 1.22.x. Anything 2+ is incompatible with the lockfiles.

Why Yarn 1, not 2/3/4. The lockfiles in these repos are Yarn-1 format. Berry (Yarn 2+) cannot read them and will produce a different dependency tree, leading to runtime errors that look like "this worked yesterday".

npm — already installed with Node¶

npm --version     # 10.x ships with Node 20

5. MySQL¶

All four backends share one MySQL database in production. For local development, you have three choices:

Option A — Connect to a shared dev DB (Recommended)¶

Verify with the team: ask for the dev/UAT MySQL connection details. This is by far the easiest path because the schema, seed data, and integrations are already set up.

Option B — Run MySQL locally with Docker¶

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

Then import the schema:

mysql -h 127.0.0.1 -u root -p someli < /home/nino/src/someli/someli-gh/someli-doc/audit/someli-api/someli-schema.sql

someli-schema.sql is the only schema artefact committed anywhere. There is no migration framework in the platform — schema changes are run by hand in production. Verify with the team which migrations have been applied since the schema file was last updated.

Option C — Install MySQL natively¶

# Ubuntu/Debian
sudo apt-get install -y mysql-server
# Fedora
sudo dnf install -y mysql-server
# macOS
brew install mysql
brew services start mysql

Then mysql -u root -p and run the schema file.

6. Git and GitHub access¶

# Make sure git is installed
git --version

# Configure identity (use your work email)
git config --global user.name "Your Name"
git config --global user.email "you@someli.ai"

# Use a credential helper so you aren't typing the password on every push
git config --global credential.helper cache

GitHub access¶

You will need an account in the Someli-ai GitHub organisation. Ask the team to add you with write access to the six product repos plus the someli-doc/ parent.
Set up SSH keys (preferred) or a personal access token. Test with:
```
ssh -T git@github.com
```

The six canonical repos you will clone:

git@github.com:Someli-ai/someli-api.git
git@github.com:Someli-ai/someli-platform.git
git@github.com:Someli-ai/Someli-Designer.git
git@github.com:Someli-ai/designer-api.git
git@github.com:Someli-ai/Someli-admin-api.git
git@github.com:Someli-ai/admin_console_R.git

Verify with the team if any of these URLs differ from the team's current remote.

7. Editor¶

Any editor that respects .editorconfig works. The project enforces 2-space indent, LF line endings, UTF-8, trim-trailing-whitespace.

VS Code (most common)¶

Install the following extensions:

EditorConfig for VS Code — picks up .editorconfig
Vetur (for someli-platform and Someli-Designer, both Vue 2) — DO NOT install Volar. Volar is the Vue 3 successor and breaks on Vue 2 single-file components.
ESLint (for admin_console_R)
Prettier (used in someli-platform)
MySQL (Cweijan's MySQL client, for poking at the DB during development)

Vue DevTools (browser extension)¶

The customer FE and the designer FE are both Vue 2. The current Vue DevTools (v7+) is Vue 3-only and breaks on Vue 2 apps — install the legacy v6.x version of Vue DevTools explicitly. Without it, inspecting components and Vuex state is much harder.

8. Useful global tools (optional)¶

# PM2 — production process manager; useful for running someli-api jobs locally
npm install --global pm2

# nodemon — auto-restarts a node process on file change. Most repos use it via `yarn start`,
# but having it global lets you run one-off scripts.
npm install --global nodemon

# concurrently — handy for starting multiple dev servers at once
npm install --global concurrently

9. Sanity check¶

Run the following — every line should succeed:

node --version             # v20.x
npm --version              # 10.x
yarn --version             # 1.22.x
git --version              # any modern git
mysql --version            # 8.x  (or skip if you'll use a remote DB)
ssh -T git@github.com      # should greet you by your GitHub username

If any of these fail, fix them before moving on. The per-module setup pages assume all of the above is working.

10. The directory layout you'll end up with¶

Most engineers clone all six repos into a single parent directory:

~/src/someli/
├── someli-api/
├── someli-platform/
├── Someli-Designer/
├── designer-api/
├── Someli-admin-api/
├── admin_console_R/
└── someli-doc/          ← this documentation tree, if you cloned it separately

This is convenient because:

Cross-repo grep -r works.
The someli-doc/CODE-OVERLAP-MATRIX.md references like-named files across repos.
You can hop between FE and BE in two cds.

It is not required — each repo is fully independent.

The fully-populated reference workspace on this machine lives at /home/nino/src/someli/someli-gh/, which is what this onboarding tree refers to. Yours will be similar.

Next¶

→ 01-platform-tour.md — what the platform actually is and how the six repos fit together.