# Deploy Quarkus to a VPS in JVM mode with Postgres

Deploy a Quarkus app to your own VPS in JVM mode: ox builds it with mvnw, runs quarkus-run.jar under systemd, checks /q/health and adds PostgreSQL for it.

To deploy Quarkus to a VPS with ox, add the repo as a project and deploy it, with no Dockerfile and no ox.toml. ox reads `pom.xml` and `mvnw`, runs `./mvnw -B -DskipTests package`, then starts `java -jar target/quarkus-app/quarkus-run.jar` 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 Quarkus repo in ox's tests. A deploy on a real server is not recorded yet.

ox reads `pom.xml` and `mvnw`, builds the plan on the card, and starts `java -jar target/quarkus-app/quarkus-run.jar` on your server. The cylinders are the services the repo asked for.

## What ox detects in a Quarkus repo

This is the plan `ox check` prints for a minimal a Quarkus app in JVM mode, 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` | `QUARKUS_HTTP_HOST=127.0.0.1 QUARKUS_HTTP_PORT=$PORT QUARKUS_HTTP_HOST_VALIDATION_REQUIRE_LOCALHOST=false java -jar target/quarkus-app/quarkus-run.jar` | `detected:pom.xml` |
| `app.health` | `/q/health` | `detected:pom.xml` |
| `build.commands[0]` | `./mvnw -B -DskipTests package` | `detected:mvnw` |
| `tools.java` | `temurin-21` | `detected:pom.xml` |
| `services.postgres` | `postgres 18 (shared)` | `detected:pom.xml` |

`ox check` also prints these hints for it:

- `the JVM sizes its heap to a quarter of the server's memory: set [app] memory (or [limits] memory) in ox.toml, and ox passes -Xmx at three quarters of it`
- `Quarkus reads QUARKUS_DATASOURCE_JDBC_URL, not DATABASE_URL: set it to jdbc:postgresql://${postgres.host}:${postgres.port}/${postgres.database}, QUARKUS_DATASOURCE_USERNAME to ${postgres.user} and QUARKUS_DATASOURCE_PASSWORD to ${postgres.password}`

## The ox.toml for Quarkus

None is needed: the plan above comes from the repo alone. Write one to serve your own domain or to change what ox detected, and to size the JVM's heap, as the hint says: ox passes -Xmx at three quarters of [app] memory. 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:

```toml
domains = ["www.example.com"]

[app]
memory = "1G"

[services]
postgres = {}
```

## Check and deploy Quarkus

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

Check, deploy and read the logs:

```sh
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 Quarkus

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 Quarkus deploy fails

- `killed by the out-of-memory killer (the build needs more memory than the project or host allows)`: The build ran out of memory. Raise the project's memory, add swap, or use a bigger server. [More](https://deploywithox.com/docs/troubleshooting#out-of-memory).
- `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](https://deploywithox.com/docs/troubleshooting#health-check-failed).
- `Java project found (pom.xml) without Spring Boot or Quarkus: ox does not know how to build and start it; add an ox.toml with [build] commands and [app] start`: ox plans Spring Boot and Quarkus. For another Java app, write `[build] commands` and `[app] start`. [More](https://deploywithox.com/docs/config#build).

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](https://deploywithox.com/docs/operate/variables#set) on the dashboard or with `ox vars`.
- [The `[app]` keys](https://deploywithox.com/docs/config#app): start, health check, memory and the rest.
- [Service dashboards](https://deploywithox.com/docs/operate/services): your database's status, size, backups and data.
- [Add a custom domain](https://deploywithox.com/docs/operate/domains) with one A record; Caddy gets the HTTPS certificate.
- [Read the logs](https://deploywithox.com/docs/operate/logs) live, search them, or download them.
- [Set variables and secrets](https://deploywithox.com/docs/operate/variables) on the dashboard or with `ox vars`.

## Quarkus FAQ

### Do I need a Dockerfile or an ox.toml to deploy Quarkus to a VPS?

No. ox does not use Docker, and `ox check` on a Quarkus 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 Quarkus?

Only what the plan names: `java temurin-21` (read from `pom.xml`). Your app's own dependencies are installed by the build into the release folder, not system-wide.

### Why does Quarkus not see DATABASE_URL?

Quarkus reads `QUARKUS_DATASOURCE_JDBC_URL`. Set it, with the user and password, from the service's values as the hint above shows.

## Related guides

- [**ASP.NET Core**Deploy an ASP.NET Core app to your own Linux VPS: ox installs the .NET 10 SDK, runs dotnet publish, starts the DLL under systemd, and adds PostgreSQL.](https://deploywithox.com/docs/guides/aspnet-core)
- [**Rust**Deploy a Rust web app from a Cargo workspace to your own VPS: ox installs stable Rust, runs cargo build --release --locked, and starts the binary.](https://deploywithox.com/docs/guides/rust)

Every stack ox deploys, and the ones it does not yet, is on the [Stacks page](https://deploywithox.com/docs/guides).

Last updated 2026-10-09. The page as HTML: https://deploywithox.com/docs/guides/quarkus