Documentation

Everything you need to know to deploy your app on Neul.

Projects & Autopacks

A project is your application on Neul. Each project has one linked repository, one or more environments, and a build history.

When you create a project, you choose an autopack — a preconfigured runtime that tells Neul how to build and run your app. Autopacks handle the build command, start command, and port configuration automatically.

Available autopacks include:

  • Bun — for TypeScript and JavaScript projects using the Bun runtime
  • Neulix — for apps built with the Neulix React SSR framework

If your autopack has a template repository, Neul can scaffold a new repo on GitHub for you when you create the project.

GitHub Integration

Neul connects to your GitHub account to access your repositories and trigger builds.

Setup:

  1. Go to Settings and click "Connect GitHub"
  2. Authorize Neul on GitHub and install the app on your account or organization
  3. Back in Neul, select which installation to link

Once connected, go to your project's Repository page, search your repos, and link the one you want to deploy. This gives Neul read access to clone and build your code.

You can have one GitHub connection per account.

Builds

A build takes your source code from GitHub, compiles it, and creates a container image ready for deployment.

To trigger a build:

  1. Go to your project's Builds page
  2. Click "New build" and select a branch
  3. Neul clones your repo, runs the build command, and packages the result

You can watch build progress in real-time. Builds go through statuses: Pending → Building → Succeeded or Failed. If a build fails, you'll see the error message and which phase failed.

Only successful builds can be deployed to environments.

Instance Slots

Neul uses a prepaid model. An instance slot is your prepaid allocation — one slot powers one running environment for 30 days.

How it works:

  • Purchase a slot from the Instances page
  • The slot is active for 30 days from purchase
  • Link it to an environment when you create one
  • Renew before expiry to keep your environment running
  • If a slot expires, the linked environment is automatically stopped

Each slot includes: 0.5 vCPU, 512 MB RAM, shared disk, unlimited deploys, and custom domain support.

You can move slots between environments. If you delete an environment, its slot becomes available again.

Environments

An environment is where your app runs. Each environment has its own subdomain, secrets, and deployment history.

Types:

  • Production — one per project. Gets the clean subdomain (e.g., myapp.neul.dev). If you have a custom domain, production uses the apex domain.
  • Staging / other — any name you choose. Subdomain format: myapp-staging.neul.dev. Custom domain uses staging.yourdomain.com.

Creating an environment requires an available instance slot. You assign the slot during creation.

Environment statuses: Idle (created, never deployed), Running, Stopped, Deploying.

Deployments

A deployment takes a successful build and runs it in an environment. You can deploy any successful build to any environment in the same project.

During deployment, you can watch each step:

  1. Pulling — downloading the container image
  2. Booting — starting the container
  3. Health check — verifying the app responds
  4. Switching — routing traffic to the new container
  5. Live — deployment complete, app is serving traffic

If you deploy a new build to an environment that's already running, Neul does a zero-downtime switch: the old container is replaced after the new one passes health checks.

You can redeploy the current build (restart) or deploy a different build at any time.

Environment Variables

Environment variables let you store secrets and configuration per environment. Values are encrypted and stored securely — they're never exposed in the UI after being set.

Usage:

  • Go to an environment's detail page
  • Add variables with uppercase keys (e.g., DATABASE_URL)
  • Variables are injected into the container on the next deploy
  • You can update or remove variables at any time

Changing a variable doesn't automatically restart your environment. Redeploy to pick up the new values.

Custom Domains

Every environment gets a free *.neul.dev subdomain. You can also add your own domain.

Setup:

  1. Go to your project's Domain page and enter your domain
  2. Add the DNS records shown:
    • A record — point your apex domain to the provided IP
    • CNAME record — point * to the provided target
  3. Click "Verify" — Neul checks your DNS records
  4. Once verified, HTTPS is provisioned automatically

Production environments use the apex domain (e.g., yourdomain.com). Staging environments use subdomains (e.g., staging.yourdomain.com).