Deploy your first app

Go from your code to a running app with an address: choose where the code comes from, check the build settings HCode proposes, name the project, and HCode runs the first deployment.

You need the owner, admin or member role. Viewers see "Viewers can't create projects or upload code. Ask an owner or admin to change your role." instead of the form.

#Start a project

On Projects, click New project, or Create your first project if the organisation has none yet. The Create a project page has three steps: Source, Build settings and Details.

If your organisation already has as many projects as its plan allows, HCode shows "You've reached your plan limit" with a link to View billing. See Plans and billing.

#Step 1: choose the source

Choose GitHub to deploy from a repository, or Upload to deploy a .zip.

#From GitHub

1. Click Connect GitHub. GitHub opens in a new tab and asks where to install the HCode app; pick the account or organisation that holds your repository.
2. Back in HCode, click Verify connection. GitHub confirms which installations are yours and HCode lists the repositories you gave it.
3. Pick a repository from the list. Use Search repositories… if you have many.
4. Click Continue.

A public repository works without connecting GitHub: enter its address under "Or enter a public repository URL", for example https://github.com/username/repo, and pick a Branch. Only GitHub repositories are supported. More detail is in Deploy from GitHub.

#From a zip file

1. Drag your .zip onto the drop zone, or click Choose file. The limit is 500 MB.
2. Wait for "Uploaded and ready for the next step". If the upload fails, click Retry upload.
3. Click Continue.

See Deploy from a zip file for how to package your code.

#Step 2: check the build settings

HCode looks at your code and proposes how to build and run it. The summary shows three lines:

• Build: "Automatic build" (with the framework it detected) or your Dockerfile.
• Run as: a web app on a port, or a background worker with no public port.
• Start command: the command that starts your app, or "Platform default".

If the summary looks right, click Continue. Otherwise open Adjust the plan, which opens by itself when HCode is unsure, and change:

• App type: Web app serves a website or API; Background worker runs in the background with no web address.
• Build mode: Automatic detects your framework and builds it; Dockerfile builds from your own Dockerfile.
• Start command: leave it empty to use the suggestion or the platform default.
• The port your app listens on: web apps only. A web app built from a Dockerfile can't continue until this is set, and your container must listen on that port.

#Step 3: name the project

1. Enter a Project name: letters, numbers, spaces, dots, hyphens and underscores, starting with a letter or number. Each name can be used once per organisation.
2. Leave Deploy immediately after setup ticked to start the first deployment as soon as the project exists. Untick it to create the project stopped, so you can review its settings before deploying.
3. Open Optional settings if the app needs a root directory (for a monorepo), environment variables or a health check path now. Create a project lists every option.
4. Click Create and deploy (or Create project if you unticked the deploy option).

All of these can be changed later; see Environment variables and Project settings.

#Watch the first deployment

HCode opens the new project. While the first deployment runs, the project page shows "Setting up your app" with three steps:

1. Queued: waiting to start and fetching your code.
2. Building: building your app.
3. Verifying: starting the new version and checking it runs.

The page says this usually takes one to three minutes. For a web app it shows the address the app will have, ending in .hcode.site.

When it succeeds, the page shows "Your app is live" with a link to your app, plus shortcuts to Add a custom domain and Set up backups. A background worker has no address; open its logs tab to see what it is doing.

#If the first deployment fails

The project page shows "Your first deploy didn't finish" with HCode's reading of what went wrong and a short list under "What to try next". From there you can:

• click Try again to start another deployment;
• open View the failed deploy to read the build log;
• open Check runtime logs or Adjust settings.

A failure marked "On our side" was caused by HCode, not your code, and you don't need to change anything before trying again. For common causes and fixes, see Failed deploys and Build failures.