Getting Started 6 min read

Getting Started

Create a project, choose the appropriate service type, and configure a first deployment.

Updated 2026-08-30 · 6 min readView as Markdown

Getting Started#

You create a deployable unit on NexHost by opening Dashboard → New Project and working through three questions in order: *what kind of workload is this*, *where is the code*, and *how should it build and run*. The first answer — the service type — is the most consequential because it determines whether NexHost serves files, starts and verifies a process, schedules a command, or provisions a database.

This guide gives you the complete flow once, so the rest of the documentation has a shared vocabulary: project, service, source, build, and release.

When to use this guide#

Read this page when you are onboarding a new application, onboarding a teammate, or choosing between service types for the first time. You can skip ahead to Your First Deployment if you already know which service type you need and just want the concrete archive-to-URL steps.

Before you begin#

A NexHost workspace you can access. The workspace scopes projects, services, repositories, domains, and billing.
Code that builds locally. Push or pack the same code you just verified — the platform will run the same build command remotely.
For public runtimes (Frontend Apps, Web Services): a persistent application that binds to 0.0.0.0. NexHost supplies PORT=3000 as a compatibility default and discovers the listener automatically.

Choose the right service#

The dashboard asks for a service type before it asks for source and build details. That choice is important: it determines how NexHost starts, checks, and exposes your application.

If you are deploying…	Choose…	Why it exists
HTML, CSS, JavaScript, or a framework static export	Static Site	Serves pre-built files without running a server — cheap and fast for content-driven sites.
Next.js, Nuxt, Remix, or another server-rendered UI	Frontend App	Runs a Node.js server behind a public hostname so SSR, middleware, and runtime routes work.
An API, backend, or public full-stack server	Web Service	Runs a persistent public process with automatic listener discovery and ingress; the right home for backends.
A service only other workspace services should reach	Private Service	Internal-only networking for service-to-service calls inside the workspace boundary.
A continuous queue or asynchronous process	Background Worker	A long-lived process that never serves traffic directly — ideal for consumers and processors.
A command that runs and exits on a schedule	Cron Job	A finite command on a UTC cron schedule, with exit-code-aware retries.

Warning

Do not choose a service type based only on framework name. A Next.js project with output: "export" is a Static Site; the same project with server rendering is a Frontend App. Picking the wrong type is the single most common cause of confusing first-deployment failures.

Add a source#

The source choices shown depend on the service type. They can include a local folder, ZIP archive, hosted NexHost Git repository, GitHub, GitLab, public Git URL, or an existing container image. Choose the branch and root directory when those controls are shown.

What to expect by source:

Local folder / ZIP archive — fast for first tests. Pack only source and lockfiles; generated folders such as node_modules, .git, and local .env* files should stay out of the archive.
NexHost Git repository — first-class hosted Git. Create or clone via the Next CLI or the dashboard, then push; select it as the source in New Project. See NexHost Git for the full flow.
GitHub / GitLab / public Git URL — connect an existing repository and pick the branch to track.
Existing container image — available for Web Services, Private Services, Background Workers, and Cron Jobs when the dashboard offers it. Useful when your build already happens elsewhere; see the Docker Quickstart.

When the dashboard shows Root directory, verify it points at the package that contains the build manifest (for example the folder with package.json or requirements.txt). A mis-pointed root is a frequent cause of dependency-installation failures.

Configure the release#

Set the build command, start command, output directory, and environment variables to match your application. Three rules cover most configurations:

Runtime services must bind to `0.0.0.0`. NexHost provides PORT=3000 as a compatibility default, discovers the listener automatically, and assigns the external route. Static services publish the selected output directory instead of starting a server.
Build outputs are not server processes. Do not attempt to serve a server build directory (for example .next) as static files when the site needs server rendering. Choose the correct runtime type instead.
Environment variables have scopes. Build-time values are baked into the artifact; runtime values are provided at start. Changing a build-time variable requires a new deployment. See Environment Variables for the full scoping table.

For runtime services, no health URL or public port is required. NexHost waits for a reachable TCP listener while the service starts. A process that binds only to 127.0.0.1, exits immediately, or blocks before opening its server will not become ready.

Deploy and inspect#

Start the deployment from the final review step. Follow the release in Deployments — the detail page splits output by stage so you can tell at a glance whether the failure was in source preparation, dependency installation, build, publish/startup, or TCP readiness.

What success looks like:

The release row shows a successful status and timestamp.
For public services, the dashboard displays the generated hostname for your service.
Opening that hostname returns the expected content or JSON.

What failure looks like:

A successful build followed by a failed startup readiness check almost always means the application bound only to localhost, exited immediately, or was blocked before opening a listener. These are application and configuration issues, not source issues.
Missing output or dependency errors during the build stage usually point to a wrong branch, root directory, or missing lockfile.

A successful public service receives the hostname displayed by the dashboard; add a custom domain afterwards when needed — the domain flow runs after a public release succeeds. See Custom Domains when you are ready.

Common mistakes#

Selecting Static Site for a Next.js app that uses server rendering or API routes. Fix: recreate as a Frontend App.
Binding only to 127.0.0.1 instead of 0.0.0.0. A fixed internal port such as 3000 is safe because each deployment has its own container network namespace.
Pointing the publish directory at a server build output (for example .next) rather than the static export (out or dist) or using a runtime service instead.
Changing an environment variable but not starting a new deployment for a static site, where the value is baked at build time.

Next steps#

Continue with Your First Deployment for a numbered, click-by-click walkthrough from local code to a verified public URL. If something did not behave as expected, Deployment Troubleshooting maps symptoms to the exact setting to check.