Skip to content
Klutch.sh Docs

Deploying a Portainer App

Introduction

Portainer is an open-source container management UI for Docker and Kubernetes. Deploying Portainer with a Dockerfile on Klutch.sh delivers reproducible builds, managed secrets, and persistent storage for configuration—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Portainer Dockerfile (GitHub is the only supported git source)
  • Storage for Portainer data (config, endpoints, settings)

For onboarding, see the Quick Start.

Architecture and ports

  • Portainer UI/API serves HTTP on internal port 9000; choose HTTP traffic.
  • Persistent storage is required for the /data directory.

Repository layout

portainer/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep credentials out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t portainer-local .
docker run -p 9000:9000 portainer-local

Dockerfile for Portainer (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM portainer/portainer-ce:latest


ENV PORT=9000


EXPOSE 9000
CMD ["/portainer", "--http-enabled", "--http-address", "0.0.0.0", "--http-port", "9000", "--data", "/data"]

Notes:

  • Pin the image tag (e.g., portainer/portainer-ce:2.20.x) for stability; update intentionally.
  • Initial admin user is set up via the web UI on first launch.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • PORT=9000
  • Optional: LOG_LEVEL=info

If you deploy without the Dockerfile and need Nixpacks overrides (rare for this image):

  • NIXPACKS_START_CMD=/portainer --http-enabled --http-address 0.0.0.0 --http-port 9000 --data /data

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /data — Portainer configuration, endpoints, and settings.

Ensure this path is writable inside the container.

Deploy Portainer on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 9000.
  4. Add the environment variables above and any custom flags you need.
  5. Attach a persistent volume for /data sized for your configuration and endpoint definitions.
  6. Deploy. On first login at https://example-app.klutch.sh, create the admin user and connect your Docker/Kubernetes endpoints.

Sample API usage

Authenticate (replace admin credentials after you set them):

Terminal window
curl -X POST "https://example-app.klutch.sh/api/auth" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"<admin_password>"}'

List endpoints (replace token):

Terminal window
curl -X GET "https://example-app.klutch.sh/api/endpoints" \
  -H "Authorization: Bearer <jwt_token>"

Health checks and production tips

  • Add an HTTP probe to / or /api/status (if enabled) for readiness.
  • Enforce HTTPS at the edge; forward internally to port 9000.
  • Keep admin credentials out of Git; rotate them regularly.
  • Monitor /data usage; resize before it fills.
  • Pin image versions and test upgrades in staging; back up /data before updates.

Portainer on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 9000 configured, and /data persisted, you can manage your container environments from a secure, self-hosted UI without extra YAML or workflow overhead.