https://github.com/acamb/deployer
A secure SSH-based deployment system for remote Docker container management
https://github.com/acamb/deployer
deploy deploy-workflow deployment deployment-automation deployment-workflow docker docker-deployment docker-manager go remote-deployment
Last synced: about 1 month ago
JSON representation
A secure SSH-based deployment system for remote Docker container management
- Host: GitHub
- URL: https://github.com/acamb/deployer
- Owner: acamb
- License: mit
- Created: 2025-06-18T13:59:59.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2026-03-21T14:56:04.000Z (3 months ago)
- Last Synced: 2026-03-22T05:05:05.121Z (3 months ago)
- Topics: deploy, deploy-workflow, deployment, deployment-automation, deployment-workflow, docker, docker-deployment, docker-manager, go, remote-deployment
- Language: Go
- Homepage:
- Size: 83 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.txt
- License: LICENSE.txt
Awesome Lists containing this project
README
A secure SSH-based deployment system for remote Docker container management.
Deployer is designed for homelabs and small infrastructure setups where you need simple, secure Docker deployments without the complexity of setting up a Docker registry. Instead of managing registry infrastructure, Deployer transfers Docker images directly from your development machine to the target server over SSH, making it perfect for personal projects, small teams, and homelab environments.
## Features
- **Docker Integration**: Deploy and manage Docker containers remotely: deploy, start, stop, and view logs
- **Secure Communication**: All data encrypted over SSH channels, public key authentication and host key verification
- **Revisions**: deploy multiple revisions of your application, roll back to previous versions easily
## Architecture
The system consists of two components:
- **Server**: SSH server that manages Docker containers
- **Client**: CLI tool for deployment and container management
## How It Works
Deployer simplifies Docker deployments using just two files in your project directory:
### Project Files
- **`Dockerfile`** *(optional)*: Client builds the Docker image locally
- **`compose.yml`** *(required)*: Server uses this to orchestrate the container
### Deployment Process
1. **`deployer-client deploy`**: Builds image (if Dockerfile exists), packages everything, and sends to server via SSH
2. **Server**: Receives the image and compose file, imports the image, then uses `docker-compose` to manage the container
### Remote Management
All container operations (`start`, `stop`, `restart`, `logs`) are executed on the server using docker-compose commands. Communication is secured through SSH with public key authentication.
### Deployment Options
- **With Dockerfile**: Full build and deploy - client builds image locally and transfers it
- **Compose only**: Use existing images from registries - faster for updates using pre-built images
The client supports also building through docker compose, mixing both methods as needed.
## Server Setup - Debian Package Installation (Recommended)
### 1. Download and Install Package
```bash
# Download the latest release
wget https://github.com/your-username/deployer/releases/download/vX.Y.Z/deployer-server_X.Y.Z_amd64.deb
# Install the package
sudo apt install /path/to/deployer-server_X.Y.Z_amd64.deb
```
The package automatically:
- Creates `deployer-server` system user
- Sets up systemd service
- Creates working directory `/opt/deployer`
- Generates SSH host key at `/opt/deployer/host_rsa_key`
- Adds user to docker group
- Starts the service
### 2. Add Client Public Keys
```bash
# Add client public keys to authorized_keys (one per line)
sudo -u deployer-server tee -a /opt/deployer/authorized_keys <<< "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC..."
```
### 3. Verify Installation
```bash
# Check server is running
sudo systemctl status deployer-server
# Check server is listening
ss -tlnp | grep :7676
# Verify file permissions
ls -la /opt/deployer/authorized_keys # Should be 600
ls -la /opt/deployer/host_rsa_key # Should be 600
# Test SSH connection (optional)
ssh -p 7676 deployer@localhost
```
### 4. Service Management
```bash
# Restart service after configuration changes
sudo systemctl restart deployer-server
# Stop/start service
sudo systemctl stop deployer-server
sudo systemctl start deployer-server
# View logs
sudo journalctl -u deployer-server -f
```
---
## Server Setup - Manual Installation
### 1. Build the Server
```bash
# Clone repository
git clone https://github.com/acamb/deployer.git
cd deployer
# Build server and client
make all
# Or build individually
make server # Creates bin/deployer-server
make client # Creates bin/deployer-client
```
### 2. Create System User and Directory
```bash
# Create system user
sudo useradd --system --no-create-home --shell /usr/sbin/nologin deployer-server
# Create working directory
sudo mkdir -p /opt/deployer
sudo chown deployer-server:deployer-server /opt/deployer
# Add user to docker group
sudo usermod -aG docker deployer-server
```
### 3. Generate SSH Host Key
```bash
# Generate SSH host key
sudo ssh-keygen -t rsa -b 4096 -f /opt/deployer/host_rsa_key -N ""
sudo chown deployer-server:deployer-server /opt/deployer/host_rsa_key
sudo chmod 600 /opt/deployer/host_rsa_key
```
### 4. Create Configuration File
```bash
# Create configuration file
sudo tee /opt/deployer/config.yaml <` flag to target a specific revision when the revisions are enabled.
### Build method
The client supports two build methods:
- **Dockerfile**: The client builds the Docker image locally using the provided Dockerfile
- **Compose build**: The client builds the Docker image using `docker-compose build`, allowing more complex build scenarios
You can specify the build method in the client configuration file:
```yaml
build_method: dockerfile # or 'compose', defalt is 'dockerfile'
```
## Troubleshooting
### Authentication Errors
```bash
# Verify public key is in server's authorized_keys
ssh -i ~/.ssh/deployer_key deployer@server-host -p 7676
# Check server logs for authentication errors (package installation)
sudo journalctl -u deployer-server -f
# Check server logs for authentication errors (manual installation)
tail -f /var/log/deployer.log
```
### Permission Issues
```bash
# Check key permissions on client
ls -la ~/.ssh/deployer_key*
# Should be: 600 for private key, 644 for public key
# Check authorized_keys permissions on server
ssh server-host "ls -la /opt/deployer/authorized_keys"
# Should be: 600
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.