Local Development Setup

July 27, 2026 ยท View on GitHub

Step-by-step guide to run LogisticsX without Docker.

Step 1: Clone Repository

git clone https://github.com/suxrobgm/logistics-app.git
cd logistics-app

Step 2: Install Angular Dependencies

cd src/Client/Logistics.Angular
bun install
cd ../../..

Step 3: Configure Database

Create the Master Database

Only the master database has to exist up front - the migrator creates each tenant database itself:

psql -U postgres -c "CREATE DATABASE master_logisticsx;"

The seeded demo tenants are us (Heartland Logistics LLC), eu (EuroFreight GmbH) and solo (Rodriguez Trucking LLC, owner-operator mode), giving you us_logisticsx, eu_logisticsx and solo_logisticsx.

Update Connection Strings

Edit src/Presentation/Logistics.API/appsettings.json:

{
  "ConnectionStrings": {
    "MasterDatabase": "Host=localhost;Port=5432;Database=master_logisticsx;Username=postgres;Password=YOUR_PASSWORD",
    "UsTenantDatabase": "Host=localhost;Port=5432;Database=us_logisticsx;Username=postgres;Password=YOUR_PASSWORD"
  },
  "TenantDatabaseDefaults": {
    "NameTemplate": "{tenant}_logisticsx",
    "Host": "localhost",
    "UserId": "postgres",
    "Password": "YOUR_PASSWORD"
  }
}

Per-request the API reads the tenant's own connection string out of the master database, so it needs no entry for eu or solo. UsTenantDatabase is only the fallback the TenantDbContext is registered with when no tenant has been resolved yet, and TenantDatabaseDefaults is what the API uses to provision a database for a newly created tenant.

Also update src/Presentation/Logistics.IdentityServer/appsettings.json with the same connection string.

The migrator has its own Tenants[] array (src/Presentation/Logistics.DbMigrator/appsettings.json) where each demo tenant carries an explicit connection string. Change the password there too, or the seed run fails. See Demo tenants (Tenants[]) for the full field list.

Step 4: Seed Databases

Run the database migrator to create tables and seed initial data:

# Using the provided script
scripts/seed-databases.cmd

# Or manually
dotnet run --project src/Presentation/Logistics.DbMigrator

The migrator applies all pending migrations automatically - master DB first, then every tenant DB - so a newly added migration needs no special step; just run it (or the Docker migrator service does it for you).

Step 5: Run Applications

Open separate terminals for each service:

Terminal 1 - API:

dotnet run --project src/Presentation/Logistics.API
# Runs on https://localhost:7000

Terminal 2 - Identity Server:

dotnet run --project src/Presentation/Logistics.IdentityServer
# Runs on https://localhost:7001

Terminal 3 - Admin Portal:

cd src/Client/Logistics.Angular
bun run start:admin
# Runs on http://localhost:7002

Terminal 4 - TMS Portal:

cd src/Client/Logistics.Angular
bun run start:tms
# Runs on http://localhost:7003

Terminal 5 - Customer Portal (Optional):

cd src/Client/Logistics.Angular
bun run start:customer
# Runs on http://localhost:7004

Or use the provided scripts:

scripts/run-api.cmd
scripts/run-identity.cmd
scripts/run-admin.cmd
scripts/run-tms.cmd
scripts/run-customer.cmd

Step 6: Configure Stripe (Optional)

For payment testing:

  1. Get your test keys from Stripe Dashboard

  2. Update src/Presentation/Logistics.API/appsettings.json:

    {
  "Stripe": {
    "SecretKey": "sk_test_...",
    "WebhookSecret": ""
  }
}

  3. Run Stripe CLI for webhook forwarding:

    scripts/listen-stripe-webhook.cmd

  4. Copy the webhook secret from Stripe CLI output and update WebhookSecret

Step 7: Access Applications

ApplicationURLCredentials
API (Swagger)https://localhost:7000/swagger-
Identity Serverhttps://localhost:7001-
Admin Portalhttp://localhost:7002admin@test.com / Test12345#
TMS Portalhttp://localhost:7003owner@test.com / Test12345#
Customer Portalhttp://localhost:7004customer1@test.com / Test12345#

Every seeded password is Test12345#. The TMS portal logs you into the us tenant; eu_owner@test.com and solo@test.com get you into the EU fleet and the owner-operator tenant. See Test Credentials for the full list.

Common Issues

HTTPS Certificate Errors

Trust the development certificate:

dotnet dev-certs https --trust

Port Already in Use

Check what's using the port:

# Windows
netstat -ano | findstr :7000

# macOS/Linux
lsof -i :7000

Database Connection Failed

  1. Verify PostgreSQL is running
  2. Check connection string credentials
  3. Ensure database exists

Angular Build Errors

cd src/Client/Logistics.Angular
bun install --force

Next Steps