Deploy Your First App

This tutorial walks you through deploying a small Next.js application from the howl-cloud/awesome-hostess examples repo. By the end, your app will be live on a public URL with automatic HTTPS.

Prerequisites

A Hostess account — sign up at hostess.sh if you don't have one
Git installed locally
Docker installed (for building images)

What You'll Deploy

A simple Next.js application running on Hostess with:

Automatic HTTPS via *.hostess.run
Zero-downtime deployments
Health checks and monitoring in Studio

Install the Hostess CLI

Terminal

curl -fsSL https://hostess.sh/install.sh | sh

Verify the installation:

Terminal

hostess --version

Example output:

hostess version 0.1.x

Log in to Hostess

Authenticate the CLI with your Hostess account:

Terminal

hostess login

The CLI prints a one-time browser link. Sign in or create an account in Studio, approve the CLI login, then return to your terminal:

Opening your browser to sign in to Hostess...

If your browser did not open, visit:
https://hostess.sh/cli/login/abc123

Waiting for browser login...
Signed in as you@example.com

Clone the example app

Clone the Hostess examples repo and move into the simple Next.js app:

Terminal

git clone https://github.com/howl-cloud/awesome-hostess.git
cd awesome-hostess/simple-next-app

The example includes the app code, Dockerfile, local Compose mirror, and Hostess config:

layout.tsx

page.tsx

Dockerfile

docker-compose.yml

hostess.yml

next.config.ts

package.json

tsconfig.json

Review the Dockerfile

The example already includes a production Dockerfile. Hostess uses it to build the Next.js app.

This Dockerfile uses Next.js standalone output mode. This is recommended for Hostess deployments.

next.config.ts

const nextConfig = {
  output: 'standalone',
};
export default nextConfig;

Review the hostess.yml

The example also includes a hostess.yml file. This is the only configuration file Hostess needs:

hostess.yml

version: "1.0"
name: simple-next-app
description: Minimal Next.js app for the Hostess deploy-your-first-app guide.

services:
  app:
    type: nextjs
    build:
      source: .
      dockerfile: Dockerfile
    resources: small

Hostess automatically:

Detects port 3000 (the default for Next.js)
Configures health checks (GET /)
Assigns a public URL with HTTPS
Runs the app with the small resource preset

The type: nextjs tells Hostess this is a Next.js application. It provides smart defaults for ports and health checks. The resources: small line keeps this tutorial inexpensive; omit it to use the default medium preset.

No Dockerfile? Even simpler. This example ships a Dockerfile for full control, but you can skip it entirely. Replace the build block with a single source line and Hostess auto-detects and builds the app for you:

hostess.yml — zero-config

services:
  app:
    type: nextjs
    source: .
    resources: small

See Build Configuration for when to use source vs build.

Deploy your app

From the awesome-hostess/simple-next-app directory, run:

Terminal

hostess deploy

If this is your first deployment, Hostess will prompt you to create a project:

No project found. Create one?
? Project name: simple-next-app
✓ Project "simple-next-app" created

Environment: preview


✓ Deployment complete (dep_abc123)

  app: https://simple-next-app-app-k7xm9p2q.hostess.run

The entire process typically takes under 2 minutes. Without --env, the CLI targets the most recently created environment in the project (on a new Hostess project, that is usually preview). Use hostess deploy --env production when you want production explicitly.

Visit your live app

Open the URL from the deployment output in your browser:

https://simple-next-app-app-k7xm9p2q.hostess.run

Your Next.js application is now live with:

Automatic HTTPS (TLS certificate provisioned by Let's Encrypt)
A stable URL that persists across future deployments
Zero-downtime deploys on every hostess deploy

View your deployment in Studio

Open the Hostess dashboard to see your deployment details at hostess.sh. In Studio, you can:

View deployment status and logs
Monitor resource usage (CPU, memory)
See deployment history
Manage environment variables and secrets

Making Changes

To deploy updates, simply make your code changes and run hostess deploy again:

Terminal

# Edit your code...
hostess deploy

Hostess performs zero-downtime deployments — your old version keeps serving traffic until the new one is healthy.

What's Next

Now that you have a basic deployment running, explore more advanced tutorials:

Next.js + FastAPI + Postgres — Add a Python backend and database to your frontend
Migrate from Docker Compose — Convert an existing multi-service project
Managing Secrets — Add API keys and credentials to your deployment
Custom Domains — Point your own domain at your app

On this page