Hosting a .NET API on Fly.io — Step by Step

# List all available regions
fly platform regions

dotnet new webapi -n MyApi --use-controllers
cd MyApi

var builder = WebApplication.CreateBuilder(args);
 
// Fly.io sets PORT at runtime; fall back to 8080 for local development
var port = Environment.GetEnvironmentVariable("PORT") ?? "8080";
builder.WebHost.UseUrls($"http://0.0.0.0:{port}");
 
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
 
var app = builder.Build();
 
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}
 
app.UseAuthorization();
app.MapControllers();
app.Run();

# syntax=docker/dockerfile:1
 
# ── Build stage ─────────────────────────────────────────────────────────────
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
 
# Copy project file first so Docker cache survives source-only changes
COPY MyApi.csproj ./
RUN dotnet restore
 
COPY . .
RUN dotnet publish -c Release -o /app/publish \
    --no-restore \
    /p:UseAppHost=false
 
# ── Runtime stage ────────────────────────────────────────────────────────────
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
WORKDIR /app
 
# Create a non-root user; Fly.io micro VMs isolate at the VM level,
# but running non-root is defence-in-depth
RUN addgroup --system appgroup && adduser --system --ingroup appgroup appuser
 
COPY --from=build /app/publish .
 
# Switch to non-root before the final CMD
USER appuser
 
ENV ASPNETCORE_ENVIRONMENT=Production
EXPOSE 8080
 
ENTRYPOINT ["dotnet", "MyApi.dll"]

docker build -t myapi:local .
docker run --rm -p 8080:8080 -e ASPNETCORE_ENVIRONMENT=Development myapi:local

# macOS / Linux
curl -L https://fly.io/install.sh | sh
 
# Windows (PowerShell)
iwr https://fly.io/install.ps1 -useb | iex
 
# Homebrew
brew install flyctl

fly auth login

fly launch

# The app name must match what you created with fly launch
app = "myapi-prod"
 
# Fly.io builds from the Dockerfile in the current directory by default
[build]
  dockerfile = "Dockerfile"
 
# Primary region — where the first instance lives
primary_region = "iad"
 
# Environment variables that are NOT secrets
# Secrets (connection strings, API keys) go in fly secrets, not here
[env]
  ASPNETCORE_ENVIRONMENT = "Production"
  DOTNET_SYSTEM_GLOBALIZATION_INVARIANT = "false"
 
# HTTP service config; Fly.io terminates TLS at the edge and forwards HTTP
[http_service]
  internal_port = 8080          # Must match EXPOSE in your Dockerfile
  force_https = true            # Redirect HTTP → HTTPS automatically
  auto_stop_machines = true     # Stop idle machines to save cost
  auto_start_machines = true    # Start a machine when a request arrives
  min_machines_running = 0      # 0 = full scale-to-zero; 1 = always-on
 
  # Health check — Fly marks the machine healthy once this returns 200
  [http_service.concurrency]
    type = "requests"
    hard_limit = 250
    soft_limit = 200
 
[[vm]]
  cpu_kind = "shared"
  cpus = 1
  memory_mb = 256

// Minimal health check — no dependencies, just confirms the process is alive
app.MapGet("/health", () => Results.Ok(new { status = "healthy", timestamp = DateTime.UtcNow }))
   .WithName("HealthCheck")
   .AllowAnonymous();

[http_service]
  internal_port = 8080
  force_https = true
 
  [[http_service.checks]]
    grace_period = "10s"   # Time to wait before first check after start
    interval = "15s"
    method = "GET"
    path = "/health"
    timeout = "5s"

# The standard deploy loop
fly deploy
 
# Watch the deployment progress
fly status --watch
 
# Tail logs after deploy
fly logs

# Set a secret (encrypted at rest, injected as env var at runtime)
fly secrets set DATABASE_URL="postgresql://user:pass@hostname/db"
 
# Set multiple at once
fly secrets set \
  JWT_SECRET="your-jwt-secret-here" \
  SENDGRID_API_KEY="SG.xxxx"
 
# List secret names (values are never shown)
fly secrets list
 
# Remove a secret
fly secrets unset SENDGRID_API_KEY

// appsettings.json has the key; the value is overridden by the env var at runtime
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseNpgsql(
        // Environment variable DATABASE_URL set via fly secrets
        builder.Configuration.GetConnectionString("Default")
        ?? Environment.GetEnvironmentVariable("DATABASE_URL")
        ?? throw new InvalidOperationException("DATABASE_URL is not set")
    )
);

# Creates a 2-node HA Postgres cluster named "myapi-db" in the iad region
fly postgres create \
  --name myapi-db \
  --region iad \
  --vm-size shared-cpu-1x \
  --volume-size 10
 
# Output includes the connection string — save it, it won't be shown again
# postgres://myapi_db:PASSWORD@myapi-db.flycast:5432/myapi_db

# Attaches the Postgres cluster to your app and sets DATABASE_URL automatically
fly postgres attach --app myapi-prod myapi-db

fly secrets list
# NAME          DIGEST    CREATED AT
# DATABASE_URL  abc123    2025-02-21T10:00:00Z

// Parse DATABASE_URL from Fly.io format: postgres://user:pass@host:port/db
var rawUrl = builder.Configuration["DATABASE_URL"]
    ?? Environment.GetEnvironmentVariable("DATABASE_URL");
 
if (!string.IsNullOrEmpty(rawUrl))
{
    var uri = new Uri(rawUrl);
    var userInfo = uri.UserInfo.Split(':');
    var connectionString = new NpgsqlConnectionStringBuilder
    {
        Host = uri.Host,
        Port = uri.Port == -1 ? 5432 : uri.Port,
        Database = uri.AbsolutePath.TrimStart('/'),
        Username = userInfo[0],
        Password = userInfo.Length > 1 ? userInfo[1] : null,
        SslMode = SslMode.Prefer,    // Fly internal network is already encrypted via WireGuard
    }.ToString();
 
    builder.Services.AddDbContext<AppDbContext>(options =>
        options.UseNpgsql(connectionString));
}

[deploy]
  release_command = "dotnet MyApi.dll migrate"

// Check for CLI args before building the full app
if (args.Contains("migrate"))
{
    // Build a minimal host just for migration
    var host = Host.CreateDefaultBuilder(args)
        .ConfigureServices((ctx, services) =>
        {
            services.AddDbContext<AppDbContext>(options =>
                options.UseNpgsql(ctx.Configuration["DATABASE_URL"]));
        })
        .Build();
 
    using var scope = host.Services.CreateScope();
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    await db.Database.MigrateAsync();
    Console.WriteLine("Migrations applied successfully.");
    return;
}
 
// Normal app startup continues below...

# Run 3 machines in the primary region (iad)
fly scale count 3
 
# Verify
fly status

# Add machines in Frankfurt and Tokyo
fly scale count 1 --region fra
fly scale count 1 --region nrt
 
# Check placement
fly status

# Keep at least one machine in each region at all times
[[regions]]
  code = "iad"
  count = 2
 
[[regions]]
  code = "lhr"
  count = 1

# Add a custom domain (you must own it)
fly certs add api.yourdomain.com
 
# Check certificate status
fly certs show api.yourdomain.com

Type  Host                Value
A     api.yourdomain.com  66.241.124.x
AAAA  api.yourdomain.com  2a09:8280:1::...

[http_service]
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 1   # Always keep one warm

<!-- MyApi.csproj — enables Native AOT compilation -->
<PropertyGroup>
  <PublishAot>true</PublishAot>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

# 1. Install flyctl and authenticate
curl -L https://fly.io/install.sh | sh
fly auth login
 
# 2. Create the app (generates fly.toml)
fly launch --name myapi-prod --region iad --no-deploy
 
# 3. Set application secrets
fly secrets set \
  JWT_SECRET="$(openssl rand -base64 32)" \
  ENVIRONMENT="Production"
 
# 4. Create and attach Postgres
fly postgres create --name myapi-db --region iad --vm-size shared-cpu-1x
fly postgres attach --app myapi-prod myapi-db
 
# 5. Deploy
fly deploy
 
# 6. Verify
fly status
fly logs
 
# 7. Open in browser
fly open