Skip to main content

Local Environment Setup

Getting a full clone (backend + frontend) running end-to-end for the first time. Assumes Prerequisites are already installed/granted.

1. Clone​

git clone <repo-url>
cd Logiswift.Eos

This is a monorepo — backend/, frontend/, eos-contracts/, docs/, and docs-internal/ all live in one Git repo but are separate build/deploy areas (their own solution/package, their own pipeline). See the root CLAUDE.md for the full layout.

2. Backend — connection string via user-secrets​

The backend never reads a real connection string from appsettings.*.json — those files ship with an empty ConnectionStrings:EosDb on purpose (see Client Onboarding for why: secrets don't live in source control for any environment, including local dev). Set it via .NET user-secrets instead, once, per machine:

cd backend/src/Logiswift.Eos.Api
dotnet user-secrets set "ConnectionStrings:EosDb" "<sandbox connection string from a teammate>"

Repeat for Logiswift.Eos.Workers and Logiswift.Eos.Api.External if you'll be running those too — each project has its own user-secrets store.

:::danger Do not Do not paste the real connection string into a commit, a doc, a chat log, or an appsettings.Development.json override. Ask for it out-of-band and store it only via dotnet user-secrets. :::

3. Backend — build, test, run​

cd backend
dotnet restore
dotnet build
dotnet test
dotnet run --project src/Logiswift.Eos.Api      # API + Swagger at /swagger
dotnet run --project src/Logiswift.Eos.Workers  # background jobs (optional for most feature work)

Confirm dotnet run --project src/Logiswift.Eos.Api comes up and GET /health reports healthy before moving on — that confirms both the build and the connection string from step 2 are good. See Build & Run for the full stack/layout reference.

4. Frontend — install and run​

eos-web depends on eos-contracts via a plain file: npm reference (not a published package), so install order doesn't matter — npm resolves it from the sibling folder automatically:

cd frontend/src/eos-web
npm install
npm run dev      # dev server, Vite — talks to the Api from step 3 via VITE_API_BASE_URL

Confirm VITE_API_BASE_URL (in .env/.env.local) points at the Api instance from step 3, then load the dev server URL in a browser and confirm the login page renders and a real login succeeds against the sandbox database.

5. You're running end-to-end when​

  • Backend GET /health is healthy.
  • Frontend dev server loads the login page and a real sandbox login succeeds.
  • dotnet test (backend) is green.

Next: Architecture Orientation for a guided tour of how the codebase is put together before your first change.