Deploy your first application

This walkthrough runs on the Engine host. It needs Docker and an internet connection to download the example image. No GPU or App account is needed.

Install and check the Engine

Follow Installation for your operating system, including Docker permissions and the correct installation method. Return when these commands work:

nerdit --version
nerdit doctor
nerdit capabilities

Use nerdit doctor to check Engine connectivity, Docker and the selected runtime. Resolve failures before deploying. The local dashboard, when bundled, is at http://localhost:9321/.

Do not run nerdit init on an installation already configured by the signed installer. Source installations have their own bootstrap steps in the installation guide.

Create an example application

In an empty working directory:

mkdir nerdit-hello
cd nerdit-hello
cat > index.html <<'EOF'
<h1>Hello from Nerdit</h1>
EOF
cat > Dockerfile <<'EOF'
FROM python:3.13-alpine
WORKDIR /app
COPY index.html .
USER 65532:65532
EXPOSE 8000
CMD ["python", "-m", "http.server", "8000", "--bind", "0.0.0.0"]
EOF
cat > nerdit.toml <<'EOF'
[deploy]
name = "nerdit-hello"
port = 8000
health = "/"
EOF

This uses Python’s standard-library HTTP server as a disposable smoke test. Use your application’s production server for a real deployment. The image listens on the declared port and runs without root privileges.

Validate and deploy

nerdit deploy . --dry-run
nerdit deploy . --wait --timeout 300
nerdit services list

The dry run validates the deployment and prints a plan without building an image or creating a service. The real deployment uploads this directory, builds the Dockerfile on the Engine host, starts a container and waits for health. The expected result is a converged deployment and a running service.A timeout exits with code 3; the deployment can still be running. Continue waiting with nerdit services wait nerdit-hello --timeout 300, or inspect nerdit diagnose nerdit-hello and nerdit logs nerdit-hello.

Open the application

By default the Caddy proxy is disabled. Find the service’s loopback endpoint in nerdit services list and open it on the Engine host. For example, if the allocated port is 9400:

curl --fail http://127.0.0.1:9400/

Use the actual port from your service, not an assumed port. The response should contain Hello from Nerdit. Loopback endpoints are not remotely reachable.For an HTTPS endpoint, follow Networking and HTTPS to enable Caddy and select a hostname and listener port, then restart the Engine using the method that manages your installation. Check nerdit proxy status and nerdit routes. In path mode, open the listed URL including /nerdit-hello/.Trust the node’s internal CA on each client after verifying its fingerprint through a trusted channel; see Networking and HTTPS. An internal certificate is not publicly trusted. A public domain and public certificate require the separate DNS and ACME steps in that guide.

Inspect and remove the example

nerdit logs nerdit-hello
nerdit diagnose nerdit-hello
nerdit services stats nerdit-hello
nerdit services stop nerdit-hello
nerdit services rm nerdit-hello --purge secrets,images

Removal deletes the service and the selected resources. Keep the source directory if you want to deploy it again. For applications with persistent data, read Backups and recovery before choosing any data purge.

Continue with Deploy applications, add AI services or managed databases, or connect the App to operate the same node from your account.

Start here

Build and operate

Access and interfaces

HTTP endpoints

Get help

Deploy your first application