Overview

Challoupe is a Docker manager you run on your own machine or inside your own network. It gives you a browser interface for containers, images, volumes, networks and full compose stacks, along with the accounts, permissions, audit trail and remote host support you would normally only find in a paid product.

There is no tier above the one you already have. Every capability described on this page ships in the same build, whether you run it on a single laptop or across several machines you manage from one place.

The rest of this documentation goes through each part of the app on its own, so pick a chapter on the left whenever you need it.

Installing Challoupe

The whole application ships as one Docker image. You do not need Node installed on your machine, you do not need to build anything by hand, and you do not need a separate database server running somewhere else. Everything Challoupe needs, its own SQLite file, your compose files, your settings, lives under a single data folder that gets mounted as a volume.

git clone https://github.com/alexis-coulombe/Challoupe.git
cd Challoupe
docker compose up -d

docker-compose.yml points at the published image, so this pulls it directly rather than building it on your own machine. If you would rather build from source instead, for instance to test a local change, docker compose up -d --build uses the included Dockerfile the same way.

Once the container is running, open the address it listens on and you will be asked to create the first account. That account becomes an administrator automatically, since there has to be one to configure anything else.

Challoupe talks to Docker through the socket at /var/run/docker.sock, so that path needs to reach the container. If you want the storage figure in the header to reflect real disk usage, also mount the host's Docker root folder at the same path inside the container, the exact path can be found by asking Docker itself for its root directory setting.

Containers

This page lists every container on whichever host is currently selected, sorted alphabetically so nothing shuffles around between refreshes. From the list you can start, stop, restart or remove a container, and a Create button walks you through an image, ports, environment variables, volumes and a restart policy.

An Advanced settings section on the same form covers what a compose file usually would: network selection, a command override, working directory, user, labels, privileged mode, whether the container removes itself once it exits, and memory or CPU limits. None of it is hidden away on a different screen, it sits right there, collapsed until you need it.

The container page

Opening a single container brings up its own page with three tabs. Logs streams live output and lets you choose how far back to look. Stats draws CPU, memory and network activity as it happens. Terminal opens a real shell inside the container straight from your browser, nothing to install on your own computer. When the AI assistant is turned on, a Diagnose button on the Logs tab reads what just happened and explains it in plain language.

Images

Images lists every image pulled or built on the current host, together with its size and every tag attached to it. Pulling something new, removing an image, or clearing out anything unused all happen from here. You can also build an image straight from a Git repository address rather than pulling something already published.

Next to a tag you may notice a small badge saying whether a newer version is available. Challoupe checks the remote registry on a timer and compares what it finds against what you have locally, so you know at a glance whether the running image still matches what the registry currently serves. No badge at all simply means it has not been checked yet, which is a different thing from being told it is current.

Volumes and networks

These two pages stay simple on purpose, since there is less to configure day to day. Volumes shows which containers use each one and lets you remove anything not attached to a container anymore. Networks lets you create a new network with the driver of your choice and remove ones you no longer need. Both lists sort alphabetically, the same reason containers do, so the order stays predictable.

Stacks

A stack in Challoupe is a compose file, kept in its own folder on disk. You can start from a blank template, pick something from the catalog covering common setups, or have the AI assistant put together a first draft from a short description if that feature is turned on.

Deploying a stack runs the real compose command underneath, so anything that already works on your own machine through the command line will work here too. Editing a stack that is already running shows you what is about to change before letting you confirm the deploy. Stopping a stack tears its containers down, and every stack's page also flags drift: a service that stopped outside Challoupe, a container Compose no longer recognizes, or one running a different image than the file calls for.

If you already keep stacks in Portainer, an import flow reads them straight from a running Portainer instance given its address and your login there, so you do not have to copy compose files over by hand.

Deploy webhooks

Every stack can have its own deploy webhook, found on that stack's page. Generating one gives you a single address containing a token, shown exactly once. Sending a plain request to that address pulls the freshest image for every service in the stack and redeploys it immediately, with no Challoupe session involved at all.

This is meant for a build pipeline. Once it pushes a new image on a tag that keeps moving, have the pipeline call that address and the running stack picks the change up right away. Only a hash of the token is ever kept on the server, so if it gets lost the only option is generating a fresh one, which retires the old one instantly.

Endpoint

The address is generated from that stack's own page, while signed in with permission to manage stacks. The call itself is POST /api/webhooks/deploy/:name/:token, no session needed, capped at 20 attempts every 15 minutes per source address.

curl -X POST https://challoupe.example.com/api/webhooks/deploy/my-stack/<token>

A successful response looks like this, with output holding whatever docker compose itself printed:

{
  "ok": true,
  "output": " Container my-stack-web-1  Started"
}

Multiple hosts

Challoupe is not limited to the machine it happens to run on. From the Hosts page, an administrator can register another machine reachable over SSH, and a switcher in the header lets anyone pick which host they are currently looking at. Containers, images, volumes, networks, and even a container's logs, live stats and terminal, all follow whichever host is selected.

Nothing extra needs to be exposed on the remote machine beyond a normal SSH login with access to Docker there, no additional port, no certificate to manage. The private key you provide gets encrypted before it ever touches the database and is never sent back to the browser once saved. Compose stacks are the one exception and always run on the local host, since the compose command itself has no equivalent path over SSH yet.

Users and permissions

Every account is either an administrator, who can do anything including managing other accounts and settings, or a regular user whose access comes from individual permissions: managing containers, images, volumes, networks or stacks, opening a terminal, and using the AI assistant or the vulnerability scanner. Reading stays open to everyone by default, lists, logs, stats, but anything that changes something, including starting or stopping a container, needs the matching permission granted first.

Any local account can turn on two factor sign in from its own account menu, scanning a QR code with an authenticator app and keeping a set of single use backup codes in case the phone is ever lost. An administrator can reset someone's two factor setup if they get locked out of it. Challoupe also supports signing in through an outside identity provider using OpenID Connect, so you can keep relying on whatever your organization already uses instead of yet another password to remember.

Notifications and alerts

Settings lets you turn on a webhook, formatted for Discord, Slack or a plain JSON consumer, and a ntfy topic if you would rather get a push notification on your phone instead. Both can be told which events actually matter to you: a container crashing, a scheduled image check turning up something newer, a resource threshold being crossed, or a scheduled backup failing.

Resource alerts watch CPU, memory and disk usage against thresholds you set yourself, on a timer you also control. Checks on individual containers apply across every host you have registered, while the reading for the machine Challoupe itself runs on only ever describes that one machine, since there is no way to read another computer's own resource usage over the same connection used to manage its containers.

System stats API

Settings' General tab has a System stats API card for outside tools: a status page, an uptime checker, anything that wants to poll Challoupe without signing in. Generating a token gives you a URL containing it, shown exactly once, that returns Docker version, container and image counts as JSON.

Add ?host=<id>, using the ID shown on the Hosts page, to read a different registered host instead of the local one. CPU, memory and disk usage are only ever included for the local host, since there is no way to read a remote machine's own resource usage over the same SSH connection used to manage its containers. Only a hash of the token is kept on the server, so revoking one and generating a fresh one is the only way to rotate it.

Endpoint

The token itself is only ever generated or revoked from the Settings UI, while signed in as an administrator. The one endpoint anything outside Challoupe actually calls is GET /api/system-stats/:token, no session or cookie needed, capped at 60 requests a minute.

curl https://challoupe.example.com/api/system-stats/<token>

# a different registered host, by ID
curl https://challoupe.example.com/api/system-stats/<token>?host=2

A successful response looks like this. Fields stay null for any host but the local one:

{
  "host": "local",
  "serverVersion": "27.3.1",
  "containersTotal": 12,
  "containersRunning": 9,
  "containersPaused": 0,
  "containersStopped": 3,
  "imagesTotal": 21,
  "memoryTotal": 16777216000,
  "cpuPercent": 4.2,
  "memoryUsed": 6291456000,
  "memoryPercent": 37.5,
  "storageUsed": 42949672960,
  "storageTotal": 214748364800,
  "storagePercent": 20
}

The AI assistant

Point Challoupe at an Ollama server, your own or one already running somewhere on your network, and three things unlock. A Diagnose button on a container's Logs tab reads what just happened and explains it in a sentence or two instead of you scrolling through a wall of text. A Generate button in the stack editor turns a short description into a first draft compose file. A floating chat button opens a small assistant aware of the containers you currently have running, so you can ask it something without leaving the page.

None of this sends anything outside your own network. The address you configure is the only place any of it ever talks to, and turning the feature off in Settings hides all three entry points from every user and disables them on the server too.

AI Watchdog

A separate switch, also in Settings, watches in the background instead of waiting for you to ask. With a model configured, it can diagnose a container the moment it crashes, gets OOM-killed, or fails its health check, folding that diagnosis straight into the crash notification sent out over whatever channels are set up under Notifications. It keeps running even with the AI assistant above turned off, since it is an independent consumer of the same Ollama connection rather than one of its user-facing entry points.

Its other check, scanning the audit log for repeated failed logins or permission denials on a timer you set, is plain rule-based logic and never calls Ollama, so it runs whether or not a model is configured.

Vulnerability scanning

From the Images page, a Scan action runs Trivy against whichever image you choose. Trivy itself runs as a single container that starts, does its work, and exits right after, nothing keeps running once the scan finishes. The first scan downloads a vulnerability database that stays cached locally afterward, so later scans come back quicker. Results arrive sorted by severity, so whatever is worth fixing first sits at the top.

Audit log

An administrator only page keeps a record of what happened across the whole app: things created or removed, changes to settings, scans that were run, sign ins, password changes and permission checks that were denied. It stays on by default and can be turned off from the page itself if you would rather not keep one, though turning it off only stops new entries from being written, it does not erase what already happened.

Backup and restore

A single export bundles every account, every setting and every stack's compose file into one file you can download whenever you like. Restoring one replaces everything currently in Challoupe and signs every open session out, since the set of valid accounts just changed under everyone at once. A scheduler can also write that same export to disk on its own timer, keeping only as many recent copies as you tell it to.

Configuration

A handful of environment variables control how Challoupe runs. Most already have a sensible default and only need your attention if your setup is unusual.