{"id":45753542,"url":"https://github.com/acamb/deployer","last_synced_at":"2026-05-22T22:00:43.790Z","repository":{"id":321660887,"uuid":"1004359903","full_name":"acamb/deployer","owner":"acamb","description":"A secure SSH-based deployment system for remote Docker container management","archived":false,"fork":false,"pushed_at":"2026-03-21T14:56:04.000Z","size":85,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-22T05:05:05.121Z","etag":null,"topics":["deploy","deploy-workflow","deployment","deployment-automation","deployment-workflow","docker","docker-deployment","docker-manager","go","remote-deployment"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acamb.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.txt","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-18T13:59:59.000Z","updated_at":"2026-03-21T14:53:55.000Z","dependencies_parsed_at":"2025-10-30T21:33:18.023Z","dependency_job_id":null,"html_url":"https://github.com/acamb/deployer","commit_stats":null,"previous_names":["acamb/deployer"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/acamb/deployer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acamb%2Fdeployer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acamb%2Fdeployer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acamb%2Fdeployer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acamb%2Fdeployer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acamb","download_url":"https://codeload.github.com/acamb/deployer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acamb%2Fdeployer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33372736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-22T21:56:13.512Z","status":"ssl_error","status_checked_at":"2026-05-22T21:56:10.769Z","response_time":265,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deploy","deploy-workflow","deployment","deployment-automation","deployment-workflow","docker","docker-deployment","docker-manager","go","remote-deployment"],"created_at":"2026-02-25T19:19:48.571Z","updated_at":"2026-05-22T22:00:43.784Z","avatar_url":"https://github.com/acamb.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"![deployer_banner.svg](img/deployer_banner.svg)\n\n![Test Status](https://github.com/acamb/deployer/actions/workflows/makefile.yml/badge.svg)\n\nA secure SSH-based deployment system for remote Docker container management.\n\nDeployer 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.\n\n## Features\n\n- **Docker Integration**: Deploy and manage Docker containers remotely: deploy, start, stop, and view logs\n- **Secure Communication**: All data encrypted over SSH channels, public key authentication and host key verification\n- **Revisions**: deploy multiple revisions of your application, roll back to previous versions easily\n\n## Architecture\n\nThe system consists of two components:\n- **Server**: SSH server that manages Docker containers\n- **Client**: CLI tool for deployment and container management\n\n## How It Works\n\nDeployer simplifies Docker deployments using just two files in your project directory:\n\n### Project Files\n- **`Dockerfile`** *(optional)*: Client builds the Docker image locally\n- **`compose.yml`** *(required)*: Server uses this to orchestrate the container\n\n### Deployment Process\n1. **`deployer-client deploy`**: Builds image (if Dockerfile exists), packages everything, and sends to server via SSH\n2. **Server**: Receives the image and compose file, imports the image, then uses `docker-compose` to manage the container\n\n### Remote Management\nAll container operations (`start`, `stop`, `restart`, `logs`) are executed on the server using docker-compose commands. Communication is secured through SSH with public key authentication.\n\n### Deployment Options\n- **With Dockerfile**: Full build and deploy - client builds image locally and transfers it\n- **Compose only**: Use existing images from registries - faster for updates using pre-built images\n\nThe client supports also building through docker compose, mixing both methods as needed.\n\n## Server Setup - Debian Package Installation (Recommended)\n\n### 1. Download and Install Package\n\n```bash\n# Download the latest release\nwget https://github.com/your-username/deployer/releases/download/vX.Y.Z/deployer-server_X.Y.Z_amd64.deb\n\n# Install the package\nsudo apt install /path/to/deployer-server_X.Y.Z_amd64.deb\n```\n\nThe package automatically:\n- Creates `deployer-server` system user\n- Sets up systemd service\n- Creates working directory `/opt/deployer`\n- Generates SSH host key at `/opt/deployer/host_rsa_key`\n- Adds user to docker group\n- Starts the service\n\n### 2. Add Client Public Keys\n\n```bash\n# Add client public keys to authorized_keys (one per line)\nsudo -u deployer-server tee -a /opt/deployer/authorized_keys \u003c\u003c\u003c \"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...\"\n```\n\n### 3. Verify Installation\n\n```bash\n# Check server is running\nsudo systemctl status deployer-server\n\n# Check server is listening\nss -tlnp | grep :7676\n\n# Verify file permissions\nls -la /opt/deployer/authorized_keys  # Should be 600\nls -la /opt/deployer/host_rsa_key     # Should be 600\n\n# Test SSH connection (optional)\nssh -p 7676 deployer@localhost\n```\n\n### 4. Service Management\n\n```bash\n# Restart service after configuration changes\nsudo systemctl restart deployer-server\n\n# Stop/start service\nsudo systemctl stop deployer-server\nsudo systemctl start deployer-server\n\n# View logs\nsudo journalctl -u deployer-server -f\n```\n\n---\n\n## Server Setup - Manual Installation\n\n### 1. Build the Server\n\n```bash\n# Clone repository\ngit clone https://github.com/acamb/deployer.git\ncd deployer\n\n# Build server and client\nmake all\n\n# Or build individually\nmake server  # Creates bin/deployer-server\nmake client  # Creates bin/deployer-client\n```\n\n### 2. Create System User and Directory\n\n```bash\n# Create system user\nsudo useradd --system --no-create-home --shell /usr/sbin/nologin deployer-server\n\n# Create working directory\nsudo mkdir -p /opt/deployer\nsudo chown deployer-server:deployer-server /opt/deployer\n\n# Add user to docker group\nsudo usermod -aG docker deployer-server\n```\n\n### 3. Generate SSH Host Key\n\n```bash\n# Generate SSH host key\nsudo ssh-keygen -t rsa -b 4096 -f /opt/deployer/host_rsa_key -N \"\"\nsudo chown deployer-server:deployer-server /opt/deployer/host_rsa_key\nsudo chmod 600 /opt/deployer/host_rsa_key\n```\n\n### 4. Create Configuration File\n\n```bash\n# Create configuration file\nsudo tee /opt/deployer/config.yaml \u003c\u003cEOF\nport: 7676\nlistenAddress: 0.0.0.0\nworkingDirectory: /opt/deployer\nhostKeyPath: /opt/deployer/host_rsa_key\nEOF\n\nsudo chown deployer-server:deployer-server /opt/deployer/config.yaml\n```\n\n### 5. Setup Authorized Keys\n\n```bash\n# Create authorized_keys file\nsudo touch /opt/deployer/authorized_keys\nsudo chmod 600 /opt/deployer/authorized_keys\nsudo chown deployer-server:deployer-server /opt/deployer/authorized_keys\n\n# Add client public keys (one per line)\nsudo -u deployer-server tee -a /opt/deployer/authorized_keys \u003c\u003c\u003c \"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...\"\n```\n\n### 6. Install and Start Service\n\n```bash\n# Copy binary to system path\nsudo cp bin/deployer-server /usr/bin/\n\n# Create systemd service (optional but recommended)\nsudo tee /etc/systemd/system/deployer-server.service \u003c\u003cEOF\n[Unit]\nDescription=Deployer Server\nAfter=network.target\n\n[Service]\nType=simple\nUser=deployer-server\nGroup=deployer-server\nExecStart=/usr/bin/deployer-server -config /opt/deployer/config.yaml\nRestart=always\nRestartSec=5\n\n[Install]\nWantedBy=multi-user.target\nEOF\n\n# Enable and start service\nsudo systemctl daemon-reload\nsudo systemctl enable deployer-server\nsudo systemctl start deployer-server\n```\n\n### 7. Verify Installation\n\n```bash\n# Check server is running\nsudo systemctl status deployer-server\n\n# Check server is listening\nss -tlnp | grep :7676\n\n# Verify file permissions\nls -la /opt/deployer/authorized_keys  # Should be 600\nls -la /opt/deployer/host_rsa_key     # Should be 600\n\n# Test SSH connection (optional)\nssh -p 7676 deployer@localhost\n```\n\n---\n\n## Configuration Parameters\n\n- **port**: SSH server listening port (default: 7676)\n- **listenAddress**: Bind address (default: 0.0.0.0)\n- **workingDirectory**: Working directory for containers (default: /opt/deployer)\n- **hostKeyPath**: SSH host key path (default: /opt/deployer/host_rsa_key)\n\n**⚠️ Security Requirements:**\n- `authorized_keys` file permissions: `600` (read/write owner only)\n- `host_rsa_key` file permissions: `600` (read/write owner only)\n- Owner: same user running the server (`deployer-server`)\n- Format: one public key per line (OpenSSH standard format)\n\n## Client Setup - Debian Package Installation (Recommended)\n\n### 1. Download and Install Package\n\n```bash\n# Download the latest release\nwget https://github.com/your-username/deployer/releases/download/vX.Y.Z/deployer-client_X.Y.Z_amd64.deb\n\n# Install the package\nsudo apt install /path/to/deployer-client_X.Y.Z_amd64.deb\n```\n\nThe package automatically:\n- Installs `deployer-client` binary in `/usr/bin/`\n\n### 2. Configure Client\n\nCreate a configuration file for each project / deployment:\n\n```bash\n# Create configuration file\nnano client-config.yaml\n```\n\nExample configuration:\n\n```yaml\nhost: your-server-host\nport: 7676\nname: myapp\nimage_name: myapp:latest\n#the private key is optional, by default the user keys are used.\nprivate_key: /path/to/your/private/key\n```\n\n### 3. Generate SSH Key Pair (if needed)\n\nIf you don't have an SSH key pair, create one:\n\n```bash\n# Generate SSH key pair for client authentication\nssh-keygen -t rsa -b 4096 -f ~/.ssh/deployer_key -N \"\"\n\n# Set correct permissions\nchmod 600 ~/.ssh/deployer_key\nchmod 644 ~/.ssh/deployer_key.pub\n```\n\n### 4. Authorize Client on Server\n\nAdd your public key to the server's authorized_keys:\n\n```bash\n# Copy your public key\ncat ~/.ssh/deployer_key.pub\n# Add this key to server's /opt/deployer/authorized_keys file\n```\n\n---\n\n## Client Setup - Manual Installation\n\n### 1. Generate SSH Key Pair (optional, you can use existing keys)\n\n```bash\n# Generate SSH key pair for client authentication\nssh-keygen -t rsa -b 4096 -f ~/.ssh/deployer_key -N \"\"\n\n# Set correct permissions\nchmod 600 ~/.ssh/deployer_key\nchmod 644 ~/.ssh/deployer_key.pub\n```\n\n### 2. Authorize Client on Server\n\nCopy the client's public key to the server's `authorized_keys` file:\n\n```bash\n# Method 1: Manual copy (most common)\ncat ~/.ssh/deployer_key.pub\n# Copy the output and add it to server's /opt/deployer/authorized_keys\n\n# Method 2: Using scp\nscp ~/.ssh/deployer_key.pub user@server-host:/tmp/\n# Then on server: sudo -u deployer-server tee -a /opt/deployer/authorized_keys \u003c /tmp/deployer_key.pub\n```\n\n### 3. Create Client Configuration\n\nCreate a YAML configuration file (e.g., `client-config.yaml`) for each project or deployment:\n\n```yaml\nhost: your-server-host\nport: 7676\nname: myapp\nimage_name: myapp:latest\n```\n\n**Configuration Parameters:**\n- **host**: Deployer server hostname or IP address\n- **port**: Deployer server port (default: 7676)\n- **name**: Unique deployment identifier\n- **image_name**: Docker image name to deploy\n- **private_key**: Path to SSH private key (optional, defaults to user's SSH keys)\n- **build_method**: 'dockerfile' or 'compose' (default: 'dockerfile')\n- **enable_revisions**: true/false (default: false)\n\n### 4. Build Client (if needed)\n\n```bash\n# If you built the server manually, the client is already built\n# Otherwise, build just the client:\ngit clone https://github.com/acamb/deployer.git\ncd deployer\nmake client  # Creates bin/deployer-client\n```\n\n## Usage\n\nYou must run the client from the project / deployment directory where you place your `compose.yml` and (optionally) `Dockerfile` files.\nThe `deploy` command will build the Docker image and will send the image and the compose.yml file to the server.\nThe server will use the compose.yml file to deploy and manage the container.\n\n### Client Operations\n\n```bash\ndeployer-client deploy [--prune] [--revision] [--new-revision] # Deploy application (and run docker image prune if specified)\ndeployer-client push [--prune] [--revision]\ndeployer-client start [--revision]                             # Start container\ndeployer-client stop [--revision]                              # Stop container\ndeployer-client restart [--revision]                           # Restart container\ndeployer-client logs [--revision]                              # View container logs\ndeployer-client revisions                                      # List running revisions of the application\n```\n\n\n\n### Revisions\nRevisions are the Deployer way of versioning your deployments, keeping a separate image and container for each revision.\nThis allows you to easily roll back to previous versions of your application if needed, do zero-downtime and blue-green deployments by switching between revisions and more.\nEach revision is kept in a separate folder on the server under the project working directory.\n\nTo enable revisions, add the following to your `compose.yml`:\n\n```yaml\nenable_revisions: true\n```\n\nYou can create a new revision with the `--new-revision` flag during deployment:\n\n```bash\ndeployer-client deploy --new-revision\n```\nAll the commands (except `revisions`) accept a `--revision \u003crevision_number\u003e` flag to target a specific revision when the revisions are enabled.\n\n### Build method\nThe client supports two build methods:\n- **Dockerfile**: The client builds the Docker image locally using the provided Dockerfile\n- **Compose build**: The client builds the Docker image using `docker-compose build`, allowing more complex build scenarios\n\nYou can specify the build method in the client configuration file:\n\n```yaml\nbuild_method: dockerfile  # or 'compose', defalt is 'dockerfile'\n```\n\n## Troubleshooting\n\n### Authentication Errors\n\n```bash\n# Verify public key is in server's authorized_keys\nssh -i ~/.ssh/deployer_key deployer@server-host -p 7676\n\n# Check server logs for authentication errors (package installation)\nsudo journalctl -u deployer-server -f\n\n# Check server logs for authentication errors (manual installation)\ntail -f /var/log/deployer.log\n```\n\n### Permission Issues\n\n```bash\n# Check key permissions on client\nls -la ~/.ssh/deployer_key*\n# Should be: 600 for private key, 644 for public key\n\n# Check authorized_keys permissions on server\nssh server-host \"ls -la /opt/deployer/authorized_keys\"\n# Should be: 600\n```\n\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facamb%2Fdeployer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facamb%2Fdeployer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facamb%2Fdeployer/lists"}