Skip to content

Development setup

Prerequisites

  • .NET 10 SDK (matches global.json).
  • Docker for Testcontainers-driven integration tests.
  • PostgreSQL is not required locally — Testcontainers spins one up for tests, and SQLite works for ad-hoc development.

Optional but recommended:

  • mkdocs + Python 3.11+ for the docs site (Documentation).
  • node for any JS-side tooling we add (e.g. for the visualiser frontend tests).

Clone and build

git clone https://gitlab.com/ampora/ampora.git
cd ampora
dotnet restore
dotnet build

The build resolves dependencies via Directory.Packages.props. There are no per-project version overrides; centralised package management is enforced.

Run the local stack

For a working backend with OIDC, use the Compose stack:

docker compose up --build
open http://localhost:8080

Pre-seeded users: alice (Admin), bob (Operator), carol (Viewer); password password.

Run from the IDE

Set Ampora.Web as the startup project. Default launch profile:

  • runs against SQLite at src/Ampora.Web/ampora.db,
  • ASPNETCORE_ENVIRONMENT=Development,
  • skips OIDC if the launch profile sets the right env vars.

First-time database

On first run with Database__Provider=Sqlite, Ampora creates ampora.db and applies migrations. To reset:

rm src/Ampora.Web/ampora.db*
dotnet run --project src/Ampora.Web

For Postgres dev:

docker compose up -d postgres
ConnectionStrings__Ampora="Host=localhost;Database=ampora;Username=ampora;Password=ampora;SSL Mode=Disable" \
Database__Provider=Postgres \
AMPORA_AUTO_MIGRATE=1 \
dotnet run --project src/Ampora.Web

Running tests

dotnet test                                # everything
dotnet test --filter "FullyQualifiedName!~Ampora.Integration.Tests"   # unit only
dotnet test tests/Ampora.Integration.Tests # integration only

Integration tests require Docker. See Testing for the full breakdown.

IDE

We support:

  • JetBrains Rider — .idea/ is committed.
  • Visual Studio 2022 — works with the .slnx solution.
  • VS Code with the C# Dev Kit.

The .editorconfig enforces formatting; dotnet format is run by CI in --verify-no-changes mode and will fail the build on drift.

Branching

  • master — protected, releasable at all times.
  • feature/* — your in-flight work.
  • release/* — release-candidate branches.

Commits

Commits follow the conventional-commit style:

feat(fleet): add bulk move action on Fleet page
fix(opamp): reject frames over MaxMessageBytes
docs: add federation tutorial
chore(ci): bump dotnet sdk to 10.0.4

The CI pipeline lints commit messages on MRs.

Pull request checklist

  • Builds clean (dotnet build and dotnet format --verify-no-changes).
  • Tests pass (dotnet test).
  • Documentation updated where behaviour changed.
  • Behavioural changes have an audit-log row reflecting the change.
  • ADR added under docs/adr/ for any architectural decision.
  • Changelog stub added under documentation/docs/release-notes.md (the release process collapses these into release sections).