Getting Started

This guide walks you from zero to your first preview URL in about five minutes. You'll sign in, connect a repository, push a commit, and share a link to your running app.

Before you begin

You need two things to follow this guide:

• A GitHub account with access to a repository you can deploy. Any stack works as long as it builds from a Dockerfile.
• A Dockerfile at the root of that repository. It should expose a single HTTP port (Nexos injects the port number via the PORT environment variable).

Don't have a Dockerfile yet? Most frameworks have a one-file example in their docs. A minimal Node.js one looks like:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Step 1 — Sign in

Open https://app.nexos.rs and click Sign in with GitHub. Nexos requests read access to your repositories and permission to install a webhook.

Step 2 — Create a project

A project in Nexos is one GitHub repository. From the dashboard, click New Project and pick the repo you want to deploy. You can accept the defaults — you can change them later.

Under the hood, Nexos:

• Installs a webhook on the repository for push and delete events.
• Generates a project slug used in preview URLs: {branch}-{project}.nexos.dev.
• Creates encrypted storage slots for any environment variables you'll add.

Step 3 — Add your secrets (optional)

If your app needs environment variables — API keys, feature flags, anything — add them under Environment Variables on your project. Values are encrypted with AES-256-GCM before they touch the database. See Environment Variables for the full story.

Step 4 — Push a branch

Push any branch to the connected repository. The webhook fires immediately.

git checkout -b feature/try-nexos
git commit --allow-empty -m "trigger a preview"
git push origin feature/try-nexos

What happens next:

1. GitHub delivers the webhook to the Nexos control plane.
2. The scheduler picks a provider node with free capacity and dispatches the build over gRPC.
3. BuildKit builds your image. In parallel, Nexos provisions Postgres, Redis, and S3 (if enabled).
4. Your container starts with DATABASE_URL, REDIS_URL, and your custom secrets injected.
5. Caddy wires up the preview URL and the environment goes live.

You'll see live build logs in the dashboard. The whole thing typically takes 30–60 seconds.

Step 5 — Open your preview URL

Find the URL at the top of the environment page. It looks like feature-try-nexos-my-app.nexos.dev. Paste it into a pull request, Slack, or your browser — reviewers can click through your running app right now.

What happens on your next push?

The second push to the same branch triggers an incremental deploy: only the app container rebuilds. The database and Redis stay intact, so your test data and user sessions survive the deploy.

Need a clean slate? Use Reset Database on the environment page. See Deployments for the full lifecycle.

Next steps

• Projects — configure builds, services, and on_deploy / on_new hooks.
• Deployments — understand brand new vs. incremental, preview URLs, restart / pause / destroy actions.
• Resource Limits — set CPU and memory ceilings and check your account quota.
• API Reference — automate the whole thing with an API key.

Running Nexos yourself

Nexos is open source. If you want to self-host the control plane and run your own nodes, follow the README in the nexos-dev/nexos repository. You'll need Docker, Node 20, pnpm, Postgres, and Redis — docker compose up -d gets the databases running in one command.