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.
What you build:
- One
alien.tsthat 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 withalien devas 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.
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
dockertoolchain builds the image from the Dockerfile on eachalien releaseand 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 port3000. TLS terminates at the load balancer, so the app serves plain HTTP. The hostname isweb.<deployment-domain>, and Alien issues the certificate in the customer's account.HOSTNAME=0.0.0.0matters: the standalone server otherwise binds to the container's hostname, and the load balancer can't reach it.- The
appprofile 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:
import type { NextConfig } from "next"
const nextConfig: NextConfig = {
// The container runs the generated .next/standalone/server.js without node_modules.
output: "standalone",
}
export default nextConfigThe Dockerfile builds in one stage and copies only the standalone output into the runtime image:
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:
export async function GET() {
return Response.json({ status: "ok" })
}Run it locally
alien init nextjs-app my-app
cd my-appFor day-to-day work, run Next.js directly:
npm run devcurl 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 devDeploy to a customer
alien login
alien link
alien release
alien onboard customer-1 --allow admin@customer-1.comalien releasebuilds the image and publishes a release.alien onboard customer-1prints a setup link, a URL that opens the setup page Alien hosts for the customer's admin.- 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.
| Platform | app runs as | web endpoint |
|---|---|---|
| AWS | Replicas on EC2 machines in the compute cluster | Load balancer with a certificate in the customer's account |
| Google Cloud | Replicas on Compute Engine machines | Google Cloud load balancing |
| Azure | Replicas on Azure VMs | Azure load balancing |
alien dev | Docker container | Local 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 theappprofile. Chat with private Postgres builds on this example that way.
Next
Hello world
One Worker with an HTTPS route and one command your backend can call, in TypeScript or Rust, from local development to a customer's cloud.
Python container
Build a locked Python project into a Container without a Dockerfile, serve HTTP from it, and call linked resources with the alienplatform SDK.