Get started

Deploy your first app

From a GitHub repository to a live HTTPS URL. Plan for about ten minutes the first time, most of it waiting on the initial build.

Before you start

You need console access (see Getting access) and a GitHub repository you can install an app on. Your repository does not need a Dockerfile — Codara can detect and build most common stacks without one.

1. Install the GitHub App

Codara reads your code through a GitHub App installation, not through your personal account. Install it on the organization or user that owns the repository:

github.com/apps/codara-cloud

Grant it access to the repositories you intend to deploy. If you skip this, the first build fails with a message telling you the app is not installed on that owner.

The installation needs these repository permissions:

Contents — read-only, to clone your code.
Commit statuses — read and write, so releases report back onto the commit.
Pull requests — read-only, for preview environments.

Built images go to Codara’s own container registry in the EU, not to GitHub, so the GitHub App needs no package permission.

2. Create your first project

Codara creates a default cloud workspace with your account. Create a project inside it; the project receives a ready production environment automatically.

In the console, select New project. Create an optional additional workspace only when you want a separate home for related projects, access and usage; additional workspaces start empty.

bash — or from the CLI

$ codaracloud projects create website \    --client my-workspace \    --name "Website"

--client takes your workspace slug; the flag keeps the API’s older name for a workspace.

Slugs become DNS names — keep them short

The workspace, project and environment slugs are combined internally and the total is capped at 63 characters. Long slugs on all three will be rejected when you create your first app. Short, lowercase, hyphenated names avoid the problem entirely.

3. Create the app

Use the console’s deploy wizard: Apps → New app. It walks the whole path in one screen and is the only surface that creates the app and starts its first build together.

Pick where it lives

Choose the workspace, then the project, then the environment — normally production.

Give a new product its own project

A project is one product, normally with its own repository. If this app is a new product rather than part of an existing one, create a project for it here instead of adding it to one that already exists. Codara will not choose for you — if the workspace has several projects and you do not pick one, the request is refused rather than guessed.

Choose the source

Select GitHub repository and pick the repo and branch. The wizard previews which builder will run before you commit to anything. You can also deploy an existing container image instead.

Set the port

Codara sends traffic to port 8080 by default and injects the chosen port into your container as PORT. If your app listens on something else, set it here — or read PORT in your code, which is the more portable habit.

Add environment variables

Anything your app needs at runtime. If your repository has an .env.example, the wizard offers its keys for you to fill in. These are runtime values only — they are deliberately not available during the build.

Deploy

Submit. The app is created and the first build is queued immediately.

Creating an app elsewhere does not build it

Only the console wizard creates an app and starts its build in one step. If you create an app through the API or an AI agent, it is left pointing at a placeholder image and will sit in a crash loop until you trigger the first build yourself with codaracloud deploy <app> --source or by pushing to the branch.

4. Watch the build

The release page shows a stepper — queued, cloning, building, pushing, rolling out, live — with build output streaming underneath. A first build usually takes a few minutes; later builds are faster because layers are cached.

Codara picks a build strategy by inspecting your repository, in this order:

If your repo has	Codara uses
Dockerfile	Your Dockerfile, exactly as written. It must be named `Dockerfile` at the build root, or be pointed at explicitly.
nixpacks.toml	Nixpacks. Opt-in — only used when this file is present.
A recognised language	Railpack, the default buildpack. Detects Node, Python, Go, Ruby, PHP, Java and others from their manifest files.
Only static assets	A generated nginx image serving those files.
None of the above	The build fails and tells you it could not detect a strategy.

5. Open your app

When the release goes live, the app is reachable over HTTPS at its workspace-scoped managed hostname. The exact label depends on whether the environment contains one service or several; for example:

https://<managed-label>-<workspace>.codara.cloud

The exact hostname is shown on the app page, and codaracloud open <app> opens it in your browser. To use your own domain instead, see Custom domains.

6. Push to deploy

Automatic deploys are on by default. From here, pushing to the branch you selected builds and releases a new version. Codara posts a commit status back to GitHub linking to the release.

bash

$ git push origin main# → build starts automatically

To release without pushing, or to rebuild a specific revision:

bash

# Build the app's configured branch$ codaracloud deploy my-api --source # Build a specific branch or commit$ codaracloud deploy my-api --branch staging$ codaracloud deploy my-api --commit a1b2c3d

deploy without a flag does not rebuild

codaracloud deploy <app> on its own just restarts the pods on the image already deployed. You must pass --source, --branch or --commit to produce a new build.

Monorepos

If several apps live in one repository, set a root directory so each app builds from its own subdirectory, and set watch paths so a push only rebuilds the apps it actually touched. A push that misses every watch path is recorded as a skipped deploy rather than silently ignored.

Where to go next

Core concepts — the model behind workspaces, projects and environments.
Environment variables — configuration and secrets.
Databases — add Postgres and wire it into your app.
Custom domains — serve on your own hostname.

Last updated 26 September 2026