serversideup/ansible repository overview

⁠Introduction

serversideup/ansible is a lightweight solution for running Ansible in a containerized environment. This project builds upon many things we learned from willhallonline/docker-ansible⁠. It provides a secure and isolated environment for running Ansible tasks, with support for both Alpine and Debian-based distributions and gives you the flexibility to run Ansible as an unprivileged user without the headaches of proper file permissions.

⁠Features

• 🐧 Debian and Alpine - Choose your OS
• 🐍 Built on official Python images - Choose your Python version
• 🔒 Unprivileged user - Choose to run as root or an unprivileged user
• 📌 Pinned Ansible Version - Set your Ansible version down to the patch version
• 🔧 Customize your "run as" user - Customize the username to run as
• 🔑 Set your own PUID and PGID - Have the PUID and PGID match your host user
• 📦 DockerHub and GitHub Container Registry - Choose where you'd like to pull your image from
• 🤖 Multi-architecture - Every image ships with x86_64 and arm64 architectures

⁠Usage

Getting started is easy. Here's a few tips on how to use this image.

⁠Choose between ansible and ansible-core

Our images are available on Docker Hub and GitHub Container Registry 🥳

DockerHub:

• serversideup/ansible⁠
• serversideup/ansible-core⁠

GitHub Container Registry:

• ghcr.io/serversideup/ansible⁠
• ghcr.io/serversideup/ansible-core⁠

Versions are made available with ansible and ansible-core. Everything is versioned appropriately according to the Ansible release process⁠.

Variation	Image Size	Description
serversideup/ansible-core		Lightweight, core installation of Ansible.
serversideup/ansible		"Batteries included" installation of Ansible.

⁠Image Tagging System

Our Docker images use a comprehensive tagging system for flexibility and specificity.

⁠Tag Components

⁠Tag Examples

⁠Run a playbook

docker run --rm -it \
  -v "$HOME/.ssh:/ssh" \
  -v "$(pwd):/ansible" \
  serversideup/ansible:latest ansible-playbook playbook.yml

⁠Change the "run as" user, PUID and PGID

docker run --rm -it \
  -v "$HOME/.ssh:/ssh" \
  -v "$(pwd):/ansible" \
  -e PUID=9999 -e PGID=9999 \
  -e RUN_AS_USER=bob \
  serversideup/ansible:latest ansible-playbook playbook.yml

⁠Run a shell

docker run --rm -it \
  -v "$HOME/.ssh:/ssh" \
  -v "$(pwd):/ansible" \
  serversideup/ansible:latest /bin/sh

⁠Working with SSH

⁠The /ssh directory

By default, we have a /ssh directory that is symbolically linked from ~/.ssh. The /ssh directory is used as our single source of truth for SSH keys and configurations.

If you set RUN_AS_USER, the entrypoint will create a home directory at /home/${RUN_AS_USER}, then create a symbolic link from /home/${RUN_AS_USER}/.ssh to /ssh. This gives you the power to set your RUN_AS_USER to anything you want without us needing to predict what user you want to run as.

⁠Mounting the SSH auth socket

The SSH auth socket is a Unix socket used by the SSH agent to communicate with other processes, allowing for secure key management. To use it with Docker, you can mount it as follows:

macOS:

docker run --rm -it \
  -v "$HOME/.ssh:/ssh:ro" \
  -v "$HOME/.ssh/known_hosts:/ssh/known_hosts:rw" \
  -v "$(pwd):/ansible" \
  -v "/run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock" \
  -e SSH_AUTH_SOCK="/run/host-services/ssh-auth.sock" \
  serversideup/ansible:latest ansible-playbook playbook.yml

Notice how we're matching the SSH_AUTH_SOCK to the host's socket. This is necessary for the SSH agent to communicate with the container.

Linux:

docker run --rm -it \
  -v "$HOME/.ssh:/ssh:ro" \
 -v "$HOME/.ssh/known_hosts:/ssh/known_hosts:rw" \
  -v "$(pwd):/ansible" \
  -v "$SSH_AUTH_SOCK:$SSH_AUTH_SOCK" \
  -e SSH_AUTH_SOCK=$SSH_AUTH_SOCK" \
  serversideup/ansible:latest ansible-playbook playbook.yml

⁠Environment Variables

You can customize the image easily with the following environment variables:

⁠Resources

• DockerHub⁠ to browse the images.
• Discord⁠ for friendly support from the community and the team.
• GitHub⁠ for source code, bug reports, and project management.
• Get Professional Help⁠ - Get video + screen-sharing help directly from the core contributors.

⁠Contributing

As an open-source project, we strive for transparency and collaboration in our development process. We greatly appreciate any contributions members of our community can provide. Whether you're fixing bugs, proposing features, improving documentation, or spreading awareness - your involvement strengthens the project. Please review our code of conduct⁠ to understand how we work together respectfully.

• Bug Report: If you're experiencing an issue while using these images, please create an issue⁠.
• Feature Request: Make this project better by submitting a feature request⁠.
• Documentation: Improve our documentation by submitting a documentation change⁠.
• Community Support: Help others on GitHub Discussions⁠ or Discord⁠.
• Security Report: Report critical security issues via our responsible disclosure policy⁠.

Need help getting started? Join our Discord community and we'll help you out!

⁠Our Sponsors

All of our software is free and open to the world. None of this can be brought to you without the financial backing of our sponsors.

⁠Platinum Sponsors

⁠Silver Sponsors

⁠Infrastructure Sponsors

These companies give us free access to the tools and infrastructure we use to build, test, and ship our open source projects. Their support helps our entire community.

⁠About Us

We're Dan⁠ and Jay⁠ - a two-person team with a passion for open source products. We created Server Side Up⁠ to help share what we learn.

Dan Pastori	Jay Rogers

⁠Hire Us

Get two senior Laravel experts who deliver quality code with predictable monthly pricing. Dan⁠ and Jay⁠ have 30+ years of combined experience building scalable Laravel applications.

• 🎯 Complete Laravel expertise - Full-stack development, CI/CD, database optimization, mobile apps
• 💰 Predictable pricing - Fixed monthly subscription, no hourly billing surprises, 40%+ savings
• ⚡ Maximum productivity - 90%+ development time, no meetings, results in days not weeks
• 🛡️ Risk-free - 7-day money-back guarantee, cancel anytime

💬 Discuss Your Project →⁠

⁠Find us at:

• 📖 Blog⁠ - Get the latest guides and free courses on all things web/mobile development.
• 🙋 Community⁠ - Get friendly help from our community members.
• 🤵‍♂️ Get Professional Help⁠ - Get video + screen-sharing support from the core contributors.
• 💻 GitHub⁠ - Check out our other open source projects.
• 📫 Newsletter⁠ - Skip the algorithms and get quality content right to your inbox.
• 🐥 X (Twitter)⁠ - You can also follow Dan⁠ and Jay⁠.
• ❤️ Sponsor Us⁠ - Please consider sponsoring us so we can create more helpful resources.

⁠Our Products

If you appreciate this project, be sure to check out our other projects.

⁠🛠️ Premium

• Self-Host Pro⁠: Sell self-hosted software in minutes.
• Spin Pro⁠: Production-ready Docker templates for shipping quickly.

⁠🌍 Open Source

• serversideup/php⁠: Supercharged PHP Docker images, based off the official PHP images.
• Spin⁠: Docker Simplified. Deploy Anywhere. Zero Downtime. Any OS.
• Financial Freedom⁠: Open source alternative to Mint, YNAB, and more.
• AmplitudeJS⁠: Customize the design of any element of the HTML5 Audio Player.
• webext-bridge⁠: Messaging in Web Extensions made easy. Batteries included.

⁠📚 Books

• Building Browser Extensions⁠: Build browser extensions for Firefox, Chrome, and more.
• Ultimate Guide To Building APIs & SPAs⁠: Build web and mobile apps from the same codebase.