Deploy ASP.NET Core to a Linux VPS with PostgreSQL

Q: Do I need a Dockerfile or an ox.toml to deploy ASP.NET Core to a Linux VPS?

No. ox does not use Docker, and ox check on a ASP.NET Core repo with no ox.toml prints Ready to deploy. Write an ox.toml only to change what ox detected.

Q: What does ox install on the server for ASP.NET Core?

Only what the plan names: the apt packages dotnet-sdk-10.0. Your app's own dependencies are installed by the build into the release folder, not system-wide.

Q: How does the app connect to PostgreSQL?

Npgsql reads a connection string, not DATABASE_URL. Set ConnectionStrings__Default from the service's values, as the hint above shows.

To deploy ASP.NET Core to a Linux VPS with ox, add the repo as a project and deploy it, with no Dockerfile and no ox.toml. ox reads src/Api/Api.csproj and src/Api/Program.cs, runs dotnet publish src/Api/Api.csproj -c Release -o out, then starts dotnet out/Api.dll under systemd behind Caddy with HTTPS, and sets up postgres 18 for it. Run ox check in your repo to see the same plan before the first deploy.

Plan verified, real-server test pending. The plan below is what ox check prints for a minimal ASP.NET Core repo in ox's tests. A deploy on a real server is not recorded yet.

ox reads src/Api/Api.csproj and src/Api/Program.cs, builds the plan on the card, and starts dotnet out/Api.dll on your server. The cylinders are the services the repo asked for.

What ox detects in a ASP.NET Core repo

This is the plan ox check prints for a minimal an ASP.NET Core app, with no ox.toml. Each row says where its value came from: a file in the repo, or ox's default.

Field	Value	Source
`app.start`	`ASPNETCORE_URLS=http://127.0.0.1:$PORT dotnet out/Api.dll`	`detected:src/Api/Api.csproj`
`app.health`	`/healthz`	`detected:src/Api/Program.cs`
`build.commands[0]`	`dotnet publish src/Api/Api.csproj -c Release -o out`	`detected:src/Api/Api.csproj`
`packages`	`dotnet-sdk-10.0`	`detected:src/Api/Api.csproj`
`services.postgres`	`postgres 18 (shared)`	`detected:src/Api/Api.csproj`

ox check also prints these hints for it:

Npgsql reads a connection string, not DATABASE_URL: set ConnectionStrings__Default to Host=${postgres.host};Port=${postgres.port};Database=${postgres.database};Username=${postgres.user};Password=${postgres.password}

The ox.toml for ASP.NET Core

None is needed: the plan above comes from the repo alone. Write one to serve your own domain or to change what ox detected. This one passes ox check against the same repo: [app] keeps the detected start command and build. Once a repo has an ox.toml, ox adds no service itself, so list each one under [services].

ox.toml, optional

domains = ["www.example.com"]

[app]

[services]
postgres = {}

Check and deploy ASP.NET Core

Add the repo as a project, then check and ship it from a terminal:

Check, deploy and read the logs

ox check                                # in the repo: the plan above, offline
ox new <owner/repo> --server <server>  # add the repo as a project
ox deploy <project> --wait              # stream the deploy, exit with its result
ox logs <project> --follow             # the app's own logs

Variables to set for ASP.NET Core

None before the first deploy: ox check asks for no variable. Add your own on the dashboard's Variables tab or with ox vars set <project> KEY.

ox provides these to the app itself: PORT, HOST, OX_ENV, OX_PROJECT, OX_RELEASE, OX_DATA_DIR, PUBLIC_URL, PUBLIC_HOST and DATABASE_URL.

If the ASP.NET Core deploy fails

several ASP.NET Core projects (src/Api/Api.csproj, src/Admin/Admin.csproj); set [build] commands to dotnet publish <project> -c Release -o out and [app] start to the one to run: Name the project to publish in [build] commands and the DLL to run in [app] start. More.
TCP connect to 127.0.0.1:8001 did not answer within 120s: dial tcp 127.0.0.1:8001: connect: connection refused: The app started but never answered on the port ox gave it. Listen on 127.0.0.1 at $PORT; the lines above the message are the app's own output. More.
web of shop on main keeps crashing: systemd restarted it 5 times in the last 10 minutes. The Logs tab shows why.: The release went live and then kept dying. Read the Logs tab for the error and deploy a fix, or roll back. More.

Your visitors never see a failed deploy: the previous release keeps serving until the new one passes its health check.

Next steps

Set variables and secrets on the dashboard or with ox vars.
The [app] keys: start, health check, memory and the rest.
Service dashboards: your database's status, size, backups and data.
Add a custom domain with one A record; Caddy gets the HTTPS certificate.
Read the logs live, search them, or download them.
Set variables and secrets on the dashboard or with ox vars.

ASP.NET Core FAQ

Do I need a Dockerfile or an ox.toml to deploy ASP.NET Core to a Linux VPS?

No. ox does not use Docker, and ox check on a ASP.NET Core repo with no ox.toml prints Ready to deploy. Write an ox.toml only to change what ox detected.

What does ox install on the server for ASP.NET Core?

Only what the plan names: the apt packages dotnet-sdk-10.0. Your app's own dependencies are installed by the build into the release folder, not system-wide.

How does the app connect to PostgreSQL?

Npgsql reads a connection string, not DATABASE_URL. Set ConnectionStrings__Default from the service's values, as the hint above shows.

Every stack ox deploys, and the ones it does not yet, is on the Stacks page.