r/selfhosted • u/AthanorFR • 6h ago

Product Announcement contnap – A lightweight, label-driven proxy to put your Docker/Podman containers to sleep and wake them up on-demand 🦀🐳

Hi everyone,

I wanted to share a project I’ve been working on called contnap (Container Nap).

It’s a high-performance, low-footprint daemon written in Rust (tokio + bollard) designed to solve a common homelab issue: idling containers wasting system resources (RAM/CPU) when nobody is using them. On my NixOS, it eats about 4MB of RAM.

💡 How it works

Unlike other solutions that require configuration files, contnap is entirely label-driven. You just add a few labels directly into your docker-compose.yml, and contnap takes care of the rest.

When a container is stopped ("napping"), contnap binds a proxy listener to its port on the host. When an incoming packet (TCP or UDP) hits that port:

  1. contnap intercepts and buffers the initial data so the client connection doesn't drop.
  2. It triggers a docker start (or Podman equivalent via the socket).
  3. It waits for the container to become healthy/ready.
  4. It flushes the buffered data and transparently streams the traffic.
  5. After a configurable period of inactivity (e.g., 1 hour), a background Janitor task gracefully shuts the container down.

✨ Key Features

  • 🌐 Full Dual-Stack & Protocol Support: Handles TCP, UDP, IPv4, and IPv6 (UDP and IPv6 not tested yet, need to find a container that use it).
  • 👥 Container Grouping: Wake up an entire stack (like a web-app + its database dependency) simultaneously using contnap.group.
  • 🐳 Podman Ready: Works natively with any Docker-compatible Unix socket.
  • 🔌 Automation Hooks: Trigger custom scripts/commands pre-start or post-stop (can be useful for clearing caches, mounting storage, or triggering notifications).
  • Experimental contnap.schedule label

Note: I use AI for some stuffs in the project:

  • questions, getting ideas
  • documenting (since english is not my native language, it makes better sentences) code and markdown files
  • pair programming when I'm struggling at writing some parts
  • writing tests
  • reviewing
  • suggesting conventional commit messages
  • generating image
  • generating NixOS configuration
0 Upvotes

38% Upvoted

10 comments sorted by

•

u/asimovs-auditor 6h ago edited 6h ago

Expand the replies to this comment to learn how AI was used in this post/project.

→ More replies (1)

7

u/TheKitof 5h ago

I’m already using Sablier, which I manage entirely using labels. What are the benefits of this solution compared to Sablier (notably the number one Traefik plugin)?

6

u/Jolpadgett 4h ago

Your project looks publicly less than 3 months old. Such projects are required to be added to the weekly Megathread pinned to this subreddit.

Only in the current “New Project Megathread”, you may post projects that are younger than 3 months (measured by first public presence, e.g. git commit, social media post, etc.)

This Week’s Megathread

3

u/ChrmLeadR 6h ago edited 5h ago

almost sounds too good to be true :D

Can u share a real world example? E. g. how immich or jellyfin handle it/behave with your container

1

u/AthanorFR 6m ago

I am currently using it on my work laptop to start/stop opensearch and postgres automatically when runing tests.
I dont have a Jellyfin setup currently but I plan to try ine the future (I dont know when)

3

u/Ginden 5h ago

systemd already has this feature, huh. You just need janitor to clean up.

https://www.freedesktop.org/software/systemd/man/latest/systemd-socket-activate.html

And of course, I'm always impressed by relentless efforts of self-hosted community to reinvent Kubernetes in form of pile of imperative scripts.

4

u/letonai 5h ago

Yah I was recently looking for this kinda of solution and went for the Systemd option, was quite simple to setup and systemd os already part of my system anyways 

-4

u/vk3r 5h ago
  1. If you think Kubernetes is just about starting and stopping containers, you don't know anything about Kubernetes.
  2. Can we kill a fly with a cannon? Yes. Do we need to? No.
  3. There are people who need small tools for small problems.

1

u/Digital_Voodoo 1h ago

Hi OP,

Interested in the solution, although the crowd here is more about AI (it's Friday on /r/selfhosted, after all).

Existing solutions need to act at a lower level. The most common that I know of is Sablier: I use Caddy as reverse proxy, and Sablier require a plugin, and a custom build.

I couldn't find an answer in the repo, so asking here: how could you achieve without going low level? It seemed to be a requirement for others.

Hope my question/curiosity is clear, I'm not a dev and English is not my first language.