Remote Host Setup

Remote Host Setup

Guide to bootstrapping strut on a remote VPS so that release, update, and other remote commands work correctly.

What release expects on the VPS

When you run strut my-stack release --env prod, strut SSHes into the VPS and expects:

1. The project repository cloned at VPS_DEPLOY_DIR (default: /home/$VPS_USER/strut)
2. The strut CLI executable at $VPS_DEPLOY_DIR/strut
3. An env file (e.g. .prod.env) in the deploy directory with production secrets
4. Docker + Docker Compose installed and accessible to VPS_USER

If any of these are missing, release will fail. The remote:init command automates steps 1–2.

Using remote:init

The fastest way to set up a new VPS:

# Stack-scoped (reads VPS_HOST, VPS_USER, etc. from your env file)
strut my-stack remote:init --env prod

# Standalone with explicit connection params
strut remote:init --host compass.local --user gfargo --key ~/.ssh/id_rsa

What it does

Step	Action
1	Tests SSH connectivity
2	Checks if strut is already installed (reports version/branch if so)
3	Clones the project repository (uses GH_PAT if set, otherwise interactive auth)
4	Makes strut executable and verifies strut --version on the remote

Options

Flag	Description
--host <host>	VPS hostname or IP (overrides VPS_HOST)
--user <user>	SSH user (overrides VPS_USER)
--key <path>	SSH key path (overrides VPS_SSH_KEY)
--port <port>	SSH port (overrides VPS_PORT, default: 22)
--repo <url>	Git repository URL (default: detected from local git remote)
--branch <name>	Branch to checkout (default: main)
--deploy-dir <path>	Remote deploy directory (overrides VPS_DEPLOY_DIR)
--dry-run	Show execution plan without making changes

Preview with dry-run

strut my-stack remote:init --env prod --dry-run

Manual setup

If you prefer to set up manually (or need to customize beyond what remote:init provides):

1. Clone the repository

# SSH into your VPS
ssh user@your-vps

# Clone with HTTPS + PAT
git clone https://oauth2:YOUR_PAT@github.com/org/repo.git ~/strut

# Or clone with SSH (requires deploy key on VPS)
git clone git@github.com:org/repo.git ~/strut

2. Make strut executable

chmod +x ~/strut/strut
~/strut/strut --version

3. Copy your env file

# From your local machine
scp .prod.env user@your-vps:~/strut/

4. Verify

ssh user@your-vps "cd ~/strut && ./strut my-stack health --env prod"

Authentication for private repos

Option A: Personal Access Token (PAT)

Set GH_PAT in your env file. strut uses it for both remote:init and update:

# In .prod.env
GH_PAT=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The PAT needs Contents (read) and Metadata (read) permissions on the repository.

Create one at: https://github.com/settings/tokens?type=beta

Option B: Deploy key (read-only, more secure)

Generate a dedicated SSH key on the VPS and add it as a deploy key on GitHub:

ssh user@your-vps "ssh-keygen -t ed25519 -f ~/.ssh/strut_deploy_key -N '' -C 'strut@your-vps'"
ssh user@your-vps "cat ~/.ssh/strut_deploy_key.pub"

Then add the public key at: Repository → Settings → Deploy keys → Add deploy key

The remote:init command offers this flow interactively when no PAT is available.

Updating strut on the VPS

After initial setup, use update to pull the latest code:

strut my-stack update --env prod

This runs git fetch && git reset --hard origin/main in the deploy directory. It requires GH_PAT for private repos.

Troubleshooting

"deploy dir not found on VPS"

strut isn't initialized on the remote. Run:

strut my-stack remote:init --env prod

"Too many authentication failures"

Your SSH agent is offering too many keys. strut v0.20.2+ adds IdentitiesOnly=yes when a key is specified. Upgrade strut or set VPS_SSH_KEY in your env file.

"Permission denied (publickey)"

The VPS doesn't accept your SSH key. Verify:

• Key permissions: chmod 600 ~/.ssh/id_rsa
• Key is in ~/.ssh/authorized_keys on the VPS
• VPS_SSH_KEY points to the correct key

Clone fails with "repository not found"

• For HTTPS: verify GH_PAT has access to the repository
• For SSH: verify the deploy key is added to the correct repository
• Check the repo URL: git remote get-url origin