Deploy your first service

You'll deploy a service from a Git repository. NebulaCtrl clones it, builds an image inside your cluster, rolls the image out to your development environment and shows you when it's healthy.

Before you beginCopy Anchor Link

• A connected cluster. See Connect a cluster. The setup wizard that opened after your first sign-in is on its second step, Link Git, when you're ready for this page.
• A GitHub repository that listens for HTTP on port 8080. NebulaCtrl builds the repository's Dockerfile. If there is none, it builds with Railpack when the repository has a package.json, go.mod, requirements.txt, Gemfile, composer.json or Cargo.toml. A Railpack build gets PORT=8080 set for you. A Dockerfile build must listen on 8080 itself.
• A GitHub account that can install an app on that repository. GitLab works too. See Git providers and registries.

1. Connect GitHubCopy Anchor Link

In the wizard's Link Git step, whose card reads Link a Git provider, select Connect on the GitHub row.

In the Connect GitHub dialog, enter a Label of up to 20 characters, for example Primary GitHub. The label can't start with "GitHub" or "Gist". Leave Host and Organization login (optional) empty for a personal github.com account. Select Continue on GitHub.

GitHub asks you to create a private GitHub App and to choose the repositories it may read. Create it and choose the repository you want to deploy.

You land on Settings > Integrations with a GitHub App connected message.

2. Return to the wizardCopy Anchor Link

Open your control plane's URL again. With no project yet, the console takes you back to the setup wizard, which opens on its first unfinished step. Its card reads Deploy your first service.

You see the Link Git step marked done, with github.com/ACCOUNT under it, where ACCOUNT is your GitHub account name.

3. Choose the repository and deployCopy Anchor Link

Find your repository in the list. Search repositories narrows it. Select it.

Select Deploy OWNER/REPOSITORY, where OWNER/REPOSITORY is the repository you picked.

You see the card title change to Deploying OWNER/REPOSITORY….

4. Watch the deploymentCopy Anchor Link

The card shows the repository, an animated stream and the environment, Development, with the release number once it exists. Under them, four stages run in order:

1. Clone repository, with the branch and short commit.
2. Build image, with the build time.
3. Push to registry, with the image digest.
4. Roll out to Development, with 1/1 healthy when it's done.

The bottom bar names what is happening, for example Building from main · 3fa9c2e, and then 1/1 replicas healthy · Development.

The build runs as a job inside your cluster, and the control plane then starts a deployment of the new release. A build can take several minutes.

When the last stage finishes, the title reads OWNER/REPOSITORY is live in Development and a Your workspace is ready card lists the Cluster, Mesh, Public and Service rows.

If a stage fails, a red box under the stages gives the reason, and the bottom bar offers Open the project. Nothing new is running, and the previous release, if there was one, keeps serving. A build fails, for example, with: no Dockerfile at Dockerfile on main and nothing recognizable to build automatically; add a Dockerfile, or add a package.json (or go.mod/requirements.txt/Gemfile/composer.json/Cargo.toml) for a project NebulaCtrl can detect.

5. Open the consoleCopy Anchor Link

Select Open the console. You land on the project's canvas with development selected. The service is a card on the canvas, and the header reads 1/1 healthy in development.

6. Check the serviceCopy Anchor Link

Select the service card. The service panel opens on the Deployments tab:

• The list holds one row, the release r-1, with status Active: it is the release serving traffic. The build b-1 that produced it appears in the release's details. A build gets its own row only while it runs or after it fails.
• Select the r-1 row to see its deployment stages. They end at Healthy.
• A note reads Auto-deploys from main, which means a push to main builds and deploys again.

Open the Logs tab to read your application's output.

VerifyCopy Anchor Link

The canvas shows the service as healthy in development, and Deployments lists r-1 as Active. The project also has a protected production environment. Nothing is deployed there, and a production deployment waits for an approval. See Change sets and approvals.

Deploy an image insteadCopy Anchor Link

If you don't use Git, deploy a ready-built image. In the wizard's Link Git step, select Skip for now. The Container image option is selected next to Template. Enter an Image such as ghcr.io/ACME/web:1.0.0 and, for a web service, an HTTP port, then select Deploy image. An image reference with a tag or digest deploys at once. One without a tag only adds the service, and you pick the version from the project afterwards.

Next stepsCopy Anchor Link