🐱 meow-litterbox

Your code’s cozy corner: a Docker litterbox that’s ready at the first meow.

meow-litterbox – Cozy Containerized Dev Environment

A portable development environment system that automates the setup of language toolchains, editors, and services inside Docker — just run a container and start coding instantly.

All container and editor configuration is managed centrally by meow, ensuring consistency with dotfiles and presets.

---

📦 Available Images

meow-litterbox provides a set of pre-built Docker images tailored for various development needs, layered for efficiency and consistency. All images are automatically published to GitHub Container Registry.

• retran/meow-litterbox-essential: The foundational image, built on Alpine Linux with Glibc. It includes:

  • Core development utilities (sudo, bash, curl, supervisor, OpenSSH).
  • The meow configuration management system pre-installed and configured for basic operations, including SSH server and Supervisord process manager.
  • A meow user configured for development, with SSH access enabled.
  • Use case: A minimal base for custom development environments or to connect via SSH/Supervisord UI.

• retran/meow-litterbox-go: Built on essential, adding:

  • The latest Go toolchain.
  • meow presets for Go development (e.g., specific linters, formatters).
  • Use case: Ideal for Go projects, especially when integrating with VS Code Dev Containers or other IDEs connecting via SSH.

• retran/meow-litterbox-go-neovim: Built on go, further adding:

  • A headless Neovim instance, pre-configured with meowvim configuration.
  • Exposes Neovim's RPC for external clients like Neovide.
  • Use case: Perfect for developers who prefer a graphical Neovim experience with a robust Go environment.

---

🏷️ Container Versioning & Tagging

meow-litterbox images published to GitHub Container Registry follow a specific versioning strategy to provide both stable releases and current development snapshots.

• Release Tags (X.Y.Z, X.Y, latest): When a semver-compatible Git tag (e.g., v1.2.3) is pushed to the repository, the corresponding Docker images are built and tagged with:

  • The full version: retran/meow-litterbox-essential:1.2.3
  • The major.minor version: retran/meow-litterbox-essential:1.2
  • The latest tag: retran/meow-litterbox-essential:latest These tags represent stable, production-ready releases.

• Development/Branch Tags (branch-name-commit-hash, branch-name-latest): For builds from specific branches (e.g., dev, feature/my-new-thing), images are tagged to reflect their origin:

  • retran/meow-litterbox-essential:dev-abcdefg (where abcdefg is the short commit hash)
  • retran/meow-litterbox-essential:dev-latest (always points to the latest build on that branch) These tags are useful for testing unreleased features or integrating with ongoing development.

• Work In Progress (WIP) Tag (wip): If a build occurs outside of a Git repository context (e.g., a local build, or when Git metadata is not available), or if the Taskfile's DOCKER_TAG variable defaults to wip, images will be tagged with wip. This tag is typically used for local development and testing, and is often seen in docker-compose.example.yml files for convenience. Example: retran/meow-litterbox-go-neovim:wip

---

⚙️ Quick Setup (using docker-compose)

This guide uses docker-compose to quickly launch a meow-litterbox container.

1. Copy & Rename Example Configuration

   Copy the default docker-compose.example.yml (which sets up the meow-litterbox-go-neovim image) to docker-compose.yml:

   cp docker-compose.example.yml docker-compose.yml

2. Review Service Definition

   Open docker-compose.yml. You'll see a litterbox service defined:

   services:
     litterbox:
       # Choose your desired image and tag.
       # For development, 'wip' is often used. For stable releases, use 'latest' or a specific version (e.g., '1.0.0', '1.0').
       # See 'Container Versioning' section for more details on available tags.
       # image: retran/meow-litterbox-essential:wip
       # image: retran/meow-litterbox-go:wip
       image: retran/meow-litterbox-go-neovim:wip
       container_name: litterbox
       restart: unless-stopped
       tty: true
       stdin_open: true
       ports:
         - "5222:22" # SSH access
         - "5201:9001" # Supervisord web UI
         - "5202:9002" # Headless Neovim RPC (only with go-neovim image)
       volumes:
         - .:/home/meow/workspace/ # Your local project mounted into the container
         - ~/.ssh:/home/meow/.ssh:ro # Your SSH keys for git/remote access
         - /var/run/docker.sock:/var/run/docker.sock # For Docker-in-Docker functionality

3. Key Configuration Points:

   • image: Select the meow-litterbox image that best suits your needs (see Available Images) and the desired tag (see Container Versioning & Tagging). The example defaults to retran/meow-litterbox-go-neovim:wip.
   • ports:
     • 5222:22 ― SSH access to the meow user.
     • 5201:9001 ― Supervisord web UI for process monitoring.
     • 5202:9002 ― Headless Neovim RPC (only relevant for go-neovim image). To avoid conflicts, you can remap these ports (e.g., - "2222:22").
   • volumes:
     • Workspace: . (your current directory) is mounted to /home/meow/workspace/ inside the container.
     • SSH Keys: ~/.ssh is mounted read-only to /home/meow/.ssh:ro for convenient access to your SSH keys.
     • Docker Socket: /var/run/docker.sock is mounted for Docker-in-Docker use cases (e.g., running tests that involve Docker).
   • container_name & restart: Customizable container name and restart policy.

---

⚡️ Usage & Editor Integration Examples

After launching your litterbox container, you can connect to it using various methods depending on your chosen image and preferred editor.

General Container Management

1. Launch the Container

   Ensure your docker-compose.yml is configured as desired, then:

   docker-compose up -d

2. Check Status & View Logs

   docker-compose ps
   docker-compose logs -f litterbox

3. Connect via SSH (Universal)

   The meow user is set up with sudo access and expects SSH key authentication. Your local ~/.ssh directory is mounted read-only into the container for convenience.

   ssh meow@localhost -p 5222

   Once inside, your project workspace will be accessible at /home/meow/workspace/.

4. Supervisord Web UI (Universal)

   Monitor and control processes (like sshd and nvim if applicable) through the Supervisord web interface:

   http://localhost:5201
   

---

A. Neovim Integration (with meow-litterbox-go-neovim)

This setup provides a fully configured Neovim environment with Go toolchain support, ideal for a graphical Neovim experience.

Example Configuration: The docker-compose.example.yml in the project root is configured for this setup. You can also find a dedicated example at examples/neovim/docker-compose.yml.

Connect with Neovide (or other Neovim GUI clients):

The meow-litterbox-go-neovim image runs Neovim in headless mode, exposing its RPC over port 9002 (mapped to 5202 by default). Point your Neovim GUI client to this server:

neovide --server localhost:5202

Ensure that port 5202 is correctly mapped to 9002 in your docker-compose.yml.

---

B. VS Code Dev Containers Integration (with meow-litterbox-go)

For a seamless development experience within VS Code, integrate meow-litterbox-go using Dev Containers. This setup provides a robust Go environment without needing the headless Neovim instance, as VS Code handles its own editor environment.

Example Configuration: A complete setup is provided in the examples/vscode directory:

• examples/vscode/.devcontainer/docker-compose.yml: Defines the litterbox service using the retran/meow-litterbox-go image (specifically the wip tag for this example).
• examples/vscode/.devcontainer/devcontainer.json: Configures VS Code to connect to this service, sets the workspace, remote user, and recommends relevant extensions (e.g., Go, Docker).

Steps to use with VS Code Dev Containers:

1. Install Dev Containers Extension: Ensure you have the Dev Containers extension installed in VS Code.
2. Open Project in VS Code: Open the examples/vscode directory in VS Code.
3. Reopen in Container: VS Code should prompt a notification asking "Folder contains a Dev Container configuration file. Reopen in Container?". Click "Reopen in Container".
   • If you don't see the prompt, open the VS Code Command Palette (F1 or Ctrl+Shift+P) and select "Dev Containers: Reopen in Container".
4. Start Coding: VS Code will automatically build (if the image is not locally present) and attach to the container. You'll have a fully configured Go development environment ready for use, with your project files mounted.

---

🔧 Advanced Tips

• Custom Image Tag To use a different tag (e.g., latest or a locally built image), update the image field in your docker-compose.yml. Refer to the Container Versioning & Tagging section for available tags.

  image: retran/meow-litterbox-go-neovim:latest

• Additional Services Add side-by-side services (databases, caches, etc.) to your docker-compose.yml to create a complete development stack:

  services:
    db:
      image: postgres:15
      environment:
        POSTGRES_PASSWORD: example
    redis:
      image: redis:7
    litterbox:
      # …existing litterbox config…

---

🙏 Acknowledgments

• Docker for making portable, reproducible environments possible.
• Alpine Linux for providing a minimal, secure base image.
• Supervisord for seamless process management inside containers.
• Go for the fantastic toolchain powering the meow-litterbox-go image.
• Neovim for the headless editor core (meow-litterbox-go-neovim).
• Go Task for automating our multi-stage build process.
• OpenSSH for reliable, secure remote access.
• The wider open-source community for all the tools and libraries that make this project possible.

---

Author

meow-litterbox is developed by Andrew Vasilyev with help from GitHub Copilot and feline assistants Sonya Blade, Mila, and Marcus Fenix.

---

Happy coding with project meow! 🐱

Made with ❤️ by Andrew Vasilyev and feline assistants

Report Bug · Request Feature · Contribute