Create a project

A project is one app, a web app or a background worker, built from a GitHub repository or a .zip file. Start one with New project on the projects page. The flow has three steps, Source, Build settings and Details, and Back keeps everything you entered.

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

#Before you start

Your plan sets how many projects the organisation can have. At the limit, the page opens "You've reached your plan limit" with your count, for example "You are using 3 of 3 projects", and a View billing button. Deleted projects don't count. Your plan's limits are on the Subscription page.

Each project created in the dashboard reserves 256 MB of your plan's memory while it runs. A stopped project uses none. Usage and limits explains how memory is counted.

#Step 1: source

Choose GitHub or Upload.

#A GitHub repository

If GitHub isn't connected yet:

1. Click Connect GitHub. GitHub opens in a new tab.
2. Install the HCode GitHub App on your account or organisation and give it the repositories you want to deploy.
3. Come back to HCode and click Verify connection.

Your repositories are then listed. Filter them with Search repositories… and select one. The project starts on the repository's default branch, which you can change later under Settings.

To deploy a public repository without connecting GitHub, paste its address under Or enter a public repository URL and pick a Branch. HCode checks that the branch exists before you continue, for example "This repository has no branch "main". Its default branch is "master"." Only GitHub addresses are accepted.

Deploy from GitHub covers private repositories and deploying on every push.

#A zip file

Drag a .zip onto the drop zone or use Choose file. The file can be up to 500 MB. It starts uploading as soon as you pick it, and creating the project waits for the upload to finish. See Deploy from a zip file.

#Step 2: build settings

For a GitHub repository, HCode reads a few files from it ("Looking at your repository to plan the deploy…") and proposes a plan:

• Build: "Automatic build", "Automatic build, detected nextjs" or "Your Dockerfile at ./Dockerfile".
• Run as: for example "Web app on port 3000" or "Background worker, no public port".
• Start command: the suggested command, or "Platform default".

It reads the root of the repository. For a monorepo, check the plan, then set the root directory in step 3.

Uploads are not inspected, so you get the defaults and the note "We do not inspect uploads, so please confirm these defaults before you deploy." If a repository can't be read in time, the heading says "Repository inspection unavailable" and you continue with the same defaults.

Open Adjust the plan to change anything. It opens by itself when the plan needs checking.

When HCode finds no web server, it preselects Background worker and says "We did not see a web server or an exposed port, so this looks like a background worker. Change it if your app serves web traffic." Web apps and workers explains the difference.

For an automatic build you can leave the port empty and HCode picks it from the build: 80 for a static site, 3000 for a server. A port you type is kept as your choice. A web app built from a Dockerfile needs a port before you can continue: "Enter the port your app listens on. Check the EXPOSE line in your Dockerfile, or use 80 for an nginx image."

#Step 3: details

Project name can use letters, numbers, spaces, dots, hyphens and underscores, must start with a letter or number, and can be up to 100 characters. A name that breaks these rules is refused with "Project name can only use letters, numbers, spaces, dots, hyphens and underscores, and must start with a letter or number." Names are unique within an organisation, and a taken name is refused with "A project named "my-app" already exists in this organization. Choose a different name."

Deploy immediately after setup is ticked by default, and the button reads Create and deploy. Untick it to create the project stopped, with a Create project button, and deploy once you have reviewed the settings.

Optional settings holds the rest:

• Root directory: the app's folder in a monorepo, for example /apps/web. Defaults to /.
• Environment variables: one KEY=value per line. A line in any other form stops the create with "invalid environment variable line". Add more later under Environment variables.
• Health check path: web apps only. See Web apps and workers.
• Install command, Build command and Output directory for an automatic build. See Automatic builds.
• The Dockerfile options for a Dockerfile build. See Dockerfile builds.

#After you create it

HCode opens the project. A deploying project shows the first deploy moving through Queued, Building and Verifying, then the app's address or what went wrong. Deploy your first app walks through that screen, and Build failures lists the problems the build recognises.