Deployment

Overview

This page covers deploying the Spiderly .NET backend as a Docker container to any hosting platform. The instructions are platform-generic — they work on Cloud Run, ECS, Azure App Service, Railway, and similar container-based services.

Dockerfile

Create a Dockerfile in your Backend/ directory:

# Build stage
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build

WORKDIR /src

COPY ["YourApp.WebAPI/YourApp.WebAPI.csproj", "YourApp.WebAPI/"]
COPY ["YourApp.Business/YourApp.Business.csproj", "YourApp.Business/"]
COPY ["YourApp.Infrastructure/YourApp.Infrastructure.csproj", "YourApp.Infrastructure/"]
COPY ["YourApp.Shared/YourApp.Shared.csproj", "YourApp.Shared/"]

RUN dotnet restore "YourApp.WebAPI/YourApp.WebAPI.csproj"

COPY . .

RUN dotnet build "YourApp.WebAPI/YourApp.WebAPI.csproj" -c Release -o /app/build

# Publish stage
FROM build AS publish
RUN dotnet publish "YourApp.WebAPI/YourApp.WebAPI.csproj" -c Release -o /app/publish /p:UseAppHost=false

# Runtime stage
FROM mcr.microsoft.com/dotnet/aspnet:9.0
WORKDIR /app

COPY --from=publish /app/publish .

EXPOSE 8080

ENTRYPOINT ["dotnet", "YourApp.WebAPI.dll"]

Database Migrations

EF Core migrations must be applied before (or during) deployment. There are two approaches.

Run Migrations Before Deployment (Recommended)

Run dotnet ef database update from your CI pipeline, pointing at the production database:

dotnet ef database update \
  --project YourApp.Infrastructure \
  --startup-project YourApp.WebAPI \
  --connection "Host=...;Database=...;Username=...;Password=..."

This keeps migrations explicit and avoids race conditions.

Run Migrations at Startup

Alternatively, apply migrations when the app starts by adding this to Startup.Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    IApplicationDbContext dbContext = app.ApplicationServices
        .CreateScope().ServiceProvider
        .GetRequiredService<IApplicationDbContext>();

    ((DbContext)dbContext).Database.Migrate();

    // ... rest of Configure
}

Local Dev Secrets

For local development, real secrets (database connection, JWT key, API tokens) live in Backend/YourApp.WebAPI/appsettings.Development.local.json. This file is gitignored and written automatically by spiderly init.

Load order for the running app:

1. appsettings.json — committed, safe defaults.
2. appsettings.Development.json — committed, dev-only overrides (e.g. local URLs).
3. appsettings.Development.local.json — gitignored, real dev secrets.
4. Environment variables — used in production.

A committed appsettings.Development.local.example.json ships alongside as a template — new developers copy it to appsettings.Development.local.json and fill in values.

Environment Variables

The generated Program.cs calls config.AddEnvironmentVariables(), so any setting from appsettings.json can be overridden with an environment variable. This is the standard way to configure secrets and per-environment values in production.

Mapping Convention

.NET uses __ (double underscore) as the separator for nested configuration keys. The mapping from appsettings.json to environment variables follows this pattern:

Required Variables

These must be set for every production deployment:

Optional Variables

CORS

The generated Startup.cs reads FrontendUrl from Spiderly.Shared settings and passes it to .WithOrigins():

builder
    .AllowAnyMethod()
    .AllowAnyHeader()
    .AllowCredentials()
    .WithOrigins(new[] { Spiderly.Shared.SettingsProvider.Current.FrontendUrl });

If you have additional frontends (e.g., a Next.js storefront), you can add more origins by overriding the CORS configuration in your Startup.Configure:

app.UseCors(builder =>
{
    builder
        .AllowAnyMethod()
        .AllowAnyHeader()
        .AllowCredentials()
        .WithOrigins(new[]
        {
            Spiderly.Shared.SettingsProvider.Current.FrontendUrl,
            YourApp.WebAPI.SettingsProvider.Current.StorefrontUrl,
        })
        .WithExposedHeaders("Content-Disposition");
});

Cookie Configuration

When your frontend and API are on different subdomains (e.g., admin.example.com and api.example.com), you need to configure cookie settings so the browser shares cookies across both.

Settings

appsettings.json

{
  "AppSettings": {
    "Spiderly.Shared": {
      "CookieDomain": ".example.com",
      "CookieSameSite": "Lax"
    }
  }
}

When to Configure

• Same-domain setup (frontend and API on same origin): No cookie configuration needed — defaults work.
• Subdomain setup (e.g., admin.example.com + api.example.com): Set CookieDomain to .example.com and CookieSameSite to Lax.
• Cross-domain setup (completely different domains): Keep CookieSameSite at None (default). The browser requires Secure cookies with SameSite=None, which Spiderly sets automatically.

Production Checklist

• ASPNETCORE_ENVIRONMENT set to Production
• ConnectionString points to the production database
• JwtKey is set to a strong, unique key (at least 32 characters)
• JwtIssuer and JwtAudience are changed from their localhost defaults
• FrontendUrl is set to the production admin panel URL (no trailing slash)
• Database migrations are applied
• CORS origins include all frontends that call the API
• Email, Telegram, and file storage variables are set (if using those features)
• CookieDomain and CookieSameSite are set (if using cookie-based authentication across subdomains)
• HTTPS is configured (via your hosting platform's load balancer or reverse proxy)