Deploy Apps with Sidekick

Sidekick is an open-source deployment CLI that runs on your local computer. It builds an application from its Dockerfile, transfers the image to an Ubuntu VPS over SSH, and runs it behind Traefik with automatic HTTPS. It is a lightweight alternative to a web-based deployment panel. Arct Cloud provides the unmanaged virtual machine. Sidekick and the applications it deploys are not preinstalled or managed by Arct Cloud; you remain responsible for server security, application data, backups, updates, and recovery.

Requirements

Basis	CPU	RAM	Storage	Operating system
Official Sidekick minimum	No numeric minimum published	No numeric minimum published	No numeric minimum published	Ubuntu LTS
Practical Arct starting point	2 vCPUs	4 GB	40 GB NVMe (`cvm.micro`)	Ubuntu 24.04 LTS

The practical recommendation is suitable for Sidekick, Traefik, and one lightweight application. Size the server for the applications you deploy, and allow additional storage for Docker images and application logs. On your local computer, you also need:

Homebrew, Sidekick, SOPS, and age
A running Docker engine
An SSH agent with the private key selected during server deployment
ssh, scp, and rsync
An application with a working Dockerfile
A domain name, or Sidekick’s default sslip.io hostname for testing

Sidekick is best suited to stateless, single-container applications on one server. It generates its own Compose definition without persistent volumes. Use an external database and object storage for persistent state, or choose a platform with a documented stateful backup and restore workflow.

Install Sidekick and Deploy an App

Deploy a fresh Ubuntu server

Deploy a server, select Ubuntu 24.04 LTS, and add an SSH key. Use a fresh VPS because sidekick init upgrades packages, installs Docker, and configures Traefik to own ports 80 and 443.Do not install Nginx, Caddy, or another Traefik instance on the same server before initialization.

Restrict inbound access

Attach and verify a network-level firewall or ACL before running Sidekick:

Ports	Source	Purpose
`22/tcp`	Your current public admin IP only	SSH administration and deployments
`80/tcp`	Any	HTTP redirect and ACME certificate issuance
`443/tcp`	Any	HTTPS application traffic
All other inbound ports	Deny	Open only when a workload explicitly requires one

Sidekick does not currently configure a firewall or rate limits. Application ports are routed inside Docker and should not be opened on the host.

Bootstrap the Sidekick account

Arct Cloud Ubuntu images use ubuntu as the default SSH user, while Sidekick initializes through either root or an existing sidekick account. Connect as ubuntu and create the account without enabling root SSH:

ssh ubuntu@YOUR_SERVER_IP

sudo useradd -m -s /bin/bash -G sudo sidekick
echo 'sidekick ALL=(ALL) NOPASSWD: ALL' \
  | sudo tee /etc/sudoers.d/sidekick >/dev/null
sudo chmod 0440 /etc/sudoers.d/sidekick
sudo visudo -cf /etc/sudoers.d/sidekick

sudo install -d -o sidekick -g sidekick -m 0700 /home/sidekick/.ssh
sudo install -o sidekick -g sidekick -m 0600 \
  /home/ubuntu/.ssh/authorized_keys \
  /home/sidekick/.ssh/authorized_keys
exit

From your local computer, verify both key access and passwordless sudo:

ssh sidekick@YOUR_SERVER_IP 'sudo -n true && echo "Sidekick account ready"'

The sidekick account receives passwordless sudo and later joins the Docker group. Either permission is effectively root-level access. Protect the SSH key and keep port 22 restricted.

Prepare your local computer

Install the current release and its secret-management dependencies with Homebrew:

brew install sidekick sops age
sidekick --version
docker version

Make sure Docker is running. Sidekick requires an SSH agent even when a key exists in the default .ssh directory:

ssh-add -l
ssh-add ~/.ssh/id_ed25519

Replace the key path when you use a different key. The first SSH connection records the server host key; verify its fingerprint before accepting it.

Initialize the VPS

Run the initializer on your local computer:

sidekick init

Enter the VPS IPv4 address and an email address for ACME certificate notices. Current Sidekick versions may also ask you to name the VPS. The initializer connects as sidekick, updates Ubuntu, installs Docker and the server-side encryption tools, and starts Traefik.Sidekick stores the age private key in its local configuration. Restrict and back up that file immediately:

chmod 600 ~/.config/sidekick/default.yaml

Keep an encrypted off-device copy. The matching age private key is required to decrypt the encrypted environment file stored on the VPS.

Verify the server

Start a new SSH session so Docker group membership takes effect, then inspect the installation:

ssh sidekick@YOUR_SERVER_IP
docker version
docker compose version
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

Confirm that Traefik is running and only expected ports are published. Do not assume the initializer disabled root or password authentication. Keep this session open and add an early SSH configuration drop-in:

sudo tee /etc/ssh/sshd_config.d/00-sidekick-hardening.conf >/dev/null <<'EOF'
PermitRootLogin no
PasswordAuthentication no
KbdInteractiveAuthentication no
EOF

sudo chmod 0644 /etc/ssh/sshd_config.d/00-sidekick-hardening.conf
sudo sshd -t
sudo systemctl reload ssh
sudo sshd -T | grep -E 'permitrootlogin|passwordauthentication|kbdinteractiveauthentication'

Verify that all three effective values are no. From a second local terminal, confirm ssh sidekick@YOUR_SERVER_IP still works before closing the original session. Use the Arct Cloud VNC console if you lose SSH access.

Prepare DNS and the application

For a custom hostname such as app.example.com, create an A record pointing to the VPS public IPv4 address. Add an AAAA record only when IPv6 is configured and reachable.In the application directory, confirm that:

Dockerfile builds successfully on your local Docker engine
The application listens on 0.0.0.0, not only 127.0.0.1
You know the container’s HTTP port
.env is excluded from Git

Test the build before deploying:

docker build -t sidekick-test .

Launch the application

From the directory containing Dockerfile, run:

sidekick launch

Provide these values when prompted:

Prompt	Example	Notes
Application name	`myapp`	Use a URL-safe, unique name
Application port	`3000`	The HTTP port inside the container, not a host port
Domain	`app.example.com`	Must resolve to this VPS; accept the generated `sslip.io` host for testing
Environment file	`.env`	Optional; Sidekick encrypts it with SOPS and age before transfer

Sidekick builds the Linux image locally, transfers it directly to the VPS without a registry, creates the Compose service, and routes the hostname through Traefik. It writes deployment metadata to sidekick.yml in the project directory.

Verify HTTPS

Wait for DNS and certificate issuance, then check the public endpoint:

curl -I https://app.example.com

Confirm the certificate hostname, application logs, and a representative request before sending production traffic.

Deploy Updates and Previews

Run a normal update from the application directory:

sidekick deploy

Sidekick rebuilds the image locally, transfers it over SSH, updates encrypted environment values when they changed, and replaces the running application. Test application-level health after every deployment; Sidekick cannot determine whether every business workflow is healthy. Preview deployments require a clean Git worktree and use the current commit hash:

sidekick preview
sidekick preview list
sidekick preview remove

Track sidekick.yml after reviewing it, but never commit .env or the global Sidekick configuration. With a custom application domain, preview URLs are subdomains of that hostname, so configure matching DNS records before relying on previews. Sidekick’s generated sslip.io hostname is simpler for initial testing.

Security, Data, and Maintenance

Sidekick’s firewall and rate-limiting support is not implemented. Keep the upstream network policy in place and review it whenever a workload changes.
The sidekick account, Docker daemon, and Traefik’s Docker socket are privileged infrastructure. A compromised deployment key can compromise every workload on the VPS.
Sidekick-managed applications share the external sidekick Docker network. Do not treat that network as isolation between mutually untrusted applications.
Store durable data in a separately backed-up service. Sidekick does not create or back up persistent volumes for the generated application service.
Back up ~/.config/sidekick/default.yaml, each project’s sidekick.yml, DNS records, and all external data stores. Test restoration on a replacement VPS.
Before brew upgrade sidekick, review the release notes and keep a recoverable copy of configuration and application data. Patch Ubuntu and monitor df -h and docker system df regularly.

Sidekick’s released documentation and current source can differ. Check sidekick --help for the commands installed on your workstation and review upstream changes before using it for a critical workload.

Troubleshooting

Sidekick cannot connect over SSH

Confirm port 22 allows your current public IP, ssh sidekick@YOUR_SERVER_IP succeeds, ssh-add -l lists the correct key, and sudo -n true works for the sidekick account. Resolve host-key warnings instead of disabling verification.

Initialization fails on ports 80 or 443

Run sudo ss -lntp | grep -E ':(80|443) ' on the VPS. Stop or remove the conflicting reverse proxy before retrying; Sidekick’s Traefik must own both ports.

HTTPS certificate issuance fails

Confirm the A record resolves to this VPS and ports 80 and 443 are reachable. Do not proxy the record through another service until the direct Sidekick route works.

Traefik returns 502 Bad Gateway

Confirm the port entered during sidekick launch matches the application’s container port and the process listens on 0.0.0.0. Inspect docker ps and the application container logs over SSH.

The local image build fails

Confirm Docker is running and build the same Dockerfile manually with docker build -t sidekick-test .. Fix the first build error before rerunning Sidekick.

A preview hostname does not resolve

Preview URLs prepend a commit hash to the application hostname. Add wildcard DNS for the custom hostname or use the generated sslip.io hostname while testing.

Official Resources

Sidekick Documentation

Official concepts, commands, and design documentation.

Sidekick on GitHub

Source code, roadmap, license, and issue tracker.

Sidekick Releases

Release binaries and version history.

Sidekick is developed by the Sidekick project. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by Sidekick.

Getting Started

Virtual Machines

Migrations

Billing & Payments

Account

Deploy Apps with Sidekick

Requirements

Install Sidekick and Deploy an App

Deploy Updates and Previews

Security, Data, and Maintenance

Troubleshooting

Official Resources

Sidekick Documentation

Sidekick on GitHub

Sidekick Releases

​Requirements

​Install Sidekick and Deploy an App

​Deploy Updates and Previews

​Security, Data, and Maintenance

​Troubleshooting

​Official Resources

Sidekick Documentation

Sidekick on GitHub

Sidekick Releases

Requirements

Install Sidekick and Deploy an App

Deploy Updates and Previews

Security, Data, and Maintenance

Troubleshooting

Official Resources