Docs

Deploy a Next.js app into a customer's cloud

This example takes an existing Next.js app and runs it in each customer's cloud account, on its own HTTPS endpoint. You keep your Next.js server and Dockerfile; Alien builds the image and runs one deployment per customer.

Architecture diagram. Left: Your cloud, alien release, Releases. Right: Customer cloud containing compute cluster containing load balancer · HTTPS; app · Next.js :3000.

Each release ships a new image. The app runs on a compute cluster behind a load balancer in the customer's account.

What you build:

  • One alien.ts that turns the Dockerfile into a Container (a long-lived service from an image) with a public endpoint.
  • A local run, first with npm run dev, then with alien dev as customers get it.
  • A release that every customer's deployment picks up without their admin.

This fits an app that must run next to the customer's data and systems: a viewer for records that can't leave their account, an internal dashboard over a private database, or an admin tool on their network. Source: examples/nextjs-app.

The Container

alien.ts turns the Dockerfile into a Container: your image as a long-lived process on machines in the customer's account.

alien.ts
import * as alien from "@alienplatform/core"

const app = new alien.Container("app")
  .code({ type: "source", src: ".", toolchain: { type: "docker", dockerfile: "Dockerfile" } })
  .cpu(0.5)
  .memory("512Mi")
  .port(3000)
  .publicEndpoint("web", 3000, "http")
  // Next's standalone server reads these; HOSTNAME=0.0.0.0 binds all interfaces.
  .environment({ PORT: "3000", HOSTNAME: "0.0.0.0" })
  .permissions("app")
  .build()

export default new alien.Stack("nextjs-app")
  .platforms(["aws", "gcp", "azure"])
  .add(app, "live")
  .permissions({ profiles: { app: {} } }) // no linked resources → empty profile
  .build()
  • The docker toolchain builds the image from the Dockerfile on each alien release and pushes it to a registry the deployment can pull from.
  • .cpu(0.5) and .memory("512Mi") are required for a Container. They size each replica and the machines Alien picks for it.
  • .publicEndpoint("web", 3000, "http") puts an HTTPS load balancer in front of port 3000. TLS terminates at the load balancer, so the app serves plain HTTP. The hostname is web.<deployment-domain>, and Alien issues the certificate in the customer's account.
  • HOSTNAME=0.0.0.0 matters: the standalone server otherwise binds to the container's hostname, and the load balancer can't reach it.
  • The app profile is empty because the app uses no other resources. When you link a database or bucket, the grants go here.
  • A Container is always live: every release replaces it.

The stack allows AWS, Google Cloud, and Azure.

Container or Worker

A Worker is stateless, event-driven compute: Lambda, Cloud Run, or Container Apps. A Container runs your image as a long-lived process on machines in the customer's account.

Next.js already ships its own server, so this example uses a Container: you don't rewrite route handlers or change how Next.js serves requests. Use a Container for any existing web server, persistent connections, or software that expects a normal process lifecycle and filesystem.

The standalone server

Next.js can emit a self-contained server that runs without node_modules. Turn it on in next.config.ts:

next.config.ts
import type { NextConfig } from "next"

const nextConfig: NextConfig = {
  // The container runs the generated .next/standalone/server.js without node_modules.
  output: "standalone",
}

export default nextConfig

The Dockerfile builds in one stage and copies only the standalone output into the runtime image:

Dockerfile
FROM node:22-alpine AS build
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm install
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production
# .next/static and public are not part of the standalone output and must be
# copied alongside it for server.js to serve them.
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
COPY --from=build /app/public ./public
ENV HOSTNAME=0.0.0.0
ENV PORT=3000
EXPOSE 3000
CMD ["node", "server.js"]

.dockerignore keeps node_modules, .next, .alien, and alien.ts out of the build context.

The app itself is one page and one API route:

app/api/health/route.ts
export async function GET() {
  return Response.json({ status: "ok" })
}

Run it locally

alien init nextjs-app my-app
cd my-app

For day-to-day work, run Next.js directly:

npm run dev
curl http://localhost:3000/api/health
{ "status": "ok" }

To run the container exactly as customers get it, use alien dev. It builds the Dockerfile, runs the image in Docker, and prints the endpoint URL:

alien dev

Deploy to a customer

alien login
alien link
alien release
alien onboard customer-1 --allow admin@customer-1.com
  1. alien release builds the image and publishes a release.
  2. alien onboard customer-1 prints a setup link, a URL that opens the setup page Alien hosts for the customer's admin.
  3. The admin picks a cloud and runs the initial setup once, with their own credentials.

You can also start initial setup from your own product, where your backend creates setup links through the API. See Deployment UX.

When the deployment is running, read the endpoint URL from the dashboard, or from GET /v1/deployments/{id}/info under resources.app.publicEndpoints.web.url. See Deployment status.

To ship a change, edit app/page.tsx and run alien release again. Every deployment on the production release channel gets the new image. The admin doesn't run anything.

What the initial setup creates

A Container needs machines. The stack doesn't declare a ComputeCluster, so on AWS, Google Cloud, and Azure Alien adds one named compute with a general pool sized from the Container. It also creates the network that Containers need.

Platformapp runs asweb endpoint
AWSReplicas on EC2 machines in the compute clusterLoad balancer with a certificate in the customer's account
Google CloudReplicas on Compute Engine machinesGoogle Cloud load balancing
AzureReplicas on Azure VMsAzure load balancing
alien devDocker containerLocal URL

The cluster is frozen: the admin creates it during the initial setup, and Alien manages the machines in it afterwards.

On AWS, the admin can also choose private endpoint access during the initial setup. The load balancer is then internal, reachable only from the customer's network. See Networking and endpoints.

Before production

  • The endpoint is open to anyone who can reach it. Add your app's normal authentication.
  • Set .minReplicas(2) for availability across machine failures. One replica means a short outage on every update.
  • To use the customer's data, add a resource such as Postgres or Storage, .link() it, and grant it in the app profile. Chat with private Postgres builds on this example that way.

Next

On this page