Skip to main content

Getting started

This guide walks you through your first deploy on AppHaven: you'll create an app, connect a Git repository, configure it, and ship it live.

Before you start​

You'll need:

  • An AppHaven account with access to the console at https://console.apphaven.eu/. If you don't have one yet, join the beta.

  • A Git repository containing your application, on GitHub or on any Git host reachable over HTTPS.

  • An apphaven.yaml manifest in the root of that repository. The manifest declares the services your app runs, the storage they keep, and their environment. If your repository has a Dockerfile, this is all it takes. AppHaven builds your image from source on every deploy:

    services:
      web:
        type: container
        build:
          dockerfile: Dockerfile
        ports:
          - 3000

    Already publishing a prebuilt image somewhere AppHaven can pull it? Use image: instead of build::

    services:
      web:
        type: container
        image: ghcr.io/your-org/your-app:latest
        ports:
          - 3000

    See The manifest for the full schema, including managed databases.

1. Create an app​

Apps live inside a project in the console. Open the project from the sidebar, then click New application. You'll be asked for:

  • Name: a short name for the app (for example my-app).
  • Description: optional, a one-line note about what the app does.
  • Region: the EU datacenter the app runs in. Region is chosen here and fixed for the life of the app; your data never leaves the EU.

Click Create application and the console takes you to the app's overview.

2. Connect your repository​

Open the app's Source tab. There are two ways to connect:

  • GitHub: connect the AppHaven GitHub App and pick the repository from the list. This is the easiest path: access stays scoped to the repositories you choose, and AppHaven is notified the moment you push.
  • Any Git host: fill in the Connect repository form with the HTTPS clone URL (for example https://git.example.com/your-org/your-app.git). Leave the credentials blank for a public repo; for a private repo, supply a username and an access token with read access.

Either way, you also choose the production branch, the branch that represents production. It defaults to main. The console verifies it can reach the repo, then lists your branches with their latest commit; your production branch is tagged Production in that list.

tip

Use Check for updates on the Source tab to pull in the latest commits from your repository, and Reconfigure to change the URL, branch, or credentials later.

3. Configure your app​

Environment variables and secrets​

Open the app's Settings tab and find Variables & Secrets. Click Add variable to add a key/value pair, choosing its type:

  • Variable: a plain value, visible in the console.
  • Secret: encrypted at rest and write-only. Once saved, the value is never shown again, to anyone. See Security: secrets.

Both kinds are added to your services' environment on every deploy, and they take precedence over a value with the same name set in the manifest. Use them for API keys and other configuration that should stay out of your repository.

Services, storage, and databases​

The shape of your running app (which services run, what ports they listen on, what storage they keep, and which databases they use) comes from the apphaven.yaml manifest in your repository. To change it, edit apphaven.yaml and push. See The manifest for every field.

4. Deploy​

With a repository connected, click Deploy on the app overview and pick a branch:

  • Your production branch deploys to production.
  • Any other branch deploys as a preview environment on its own URL, completely separate from production. Ideal for checking a change before it ships.

AppHaven reads apphaven.yaml at that branch's latest commit, builds or pulls your images, and starts your app. You can follow its progress on the overview as it moves through:

  • Provisioning: AppHaven is building or pulling your images and starting your containers.
  • Running: your app is up. The deployment card lists each container, its state, and the URL your app is served on.
  • Failed: the card shows what went wrong, with logs, so you can fix your code or manifest and deploy again.

When a deploy builds from source, the Builds tab shows each build with its full log. Once your app is running, the deployment page also shows your containers' console output, no SSH required.

You can Stop a running deployment from its card at any time. Stopping keeps its persistent data; deploying again picks it right back up.

5. Releasing updates​

To release an update, push to your production branch and deploy again. Use Check for updates on the Source tab if the console hasn't seen the new commits yet. Each deployment records exactly which commit it shipped, and your persistent data carries over from one release to the next.

If you'd rather not click at all, turn on auto-deploy on the Source tab: every push to your production branch then goes live on its own.

:::tip Preview first

A good rhythm, especially when an AI agent is writing the code, is to deploy the working branch as a preview, look at the result on its preview URL, then merge and let auto-deploy ship production.

:::

Next steps​