Connect a VPS server

To deploy, Paylood connects to your servers over SSH. No agent to install: everything is automated.

Prerequisites

• A VPS running Linux (Ubuntu recommended).
• SSH access: a user (root or another) + password or private key.
• The SSH port open (22 by default).

Connecting a server

1. Open Servers then click Connect a VPS.
2. Fill in:
   • IP address (or hostname) of the server.
   • SSH port (default 22).
   • User (e.g. root).
3. Choose the authentication:
   • Password: enter the SSH password.
   • Private key: paste your private key content (and its passphrase if used).
4. Click Test connection.

The connection test

The test streams the steps live during the SSH attempt:

1. Connecting to the server.
2. Key exchange / authentication.
3. Environment check (Docker installed?).
4. Result: success or a detailed error.

Linking an existing server to a project

During the creation wizard (SSH Config step), choose Connect an existing server: the list of your VPS appears and you link the one you want without re-entering credentials.

Editing or updating a server

If your server’s IP address, port, username, password, or SSH private key changes:

1. Go to the Servers page.
2. On the server card, click the Edit (pencil icon) button next to the delete button.
3. The edit drawer will open pre-filled with your current server details.
4. Update the label, host, port, username, or switch authentication methods (Password ↔ Private Key).
   • Note: Leave password or private key fields empty to preserve previously saved credentials.
5. Click Test Connection to verify SSH connectivity in real-time.
6. Click Update Server to save your changes.

Supported SSH Key Formats

To ensure compatibility with Paylood’s deployment engine, private keys must follow standard formats:

• OpenSSH Ed25519 (Recommended): begins with -----BEGIN OPENSSH PRIVATE KEY-----
• RSA PEM (PKCS#1): begins with -----BEGIN RSA PRIVATE KEY-----

Tutorial: Fixing Cannot parse privateKey: Unsupported key format

If you encounter this error during deployment or connection testing:

ERROR: Cannot parse privateKey: Unsupported key format

it means the private key stored for your server is invalid, truncated, or in an unsupported format.

Follow these steps to generate a clean OpenSSH key and update your server:

Step 1: Generate an OpenSSH key pair

On your local terminal (Linux, macOS, or Windows PowerShell):

# Generate a standard OpenSSH Ed25519 key pair:
ssh-keygen -t ed25519 -C "paylood-server" -f ~/.ssh/paylood_ed25519 -N ""

This creates:

• ~/.ssh/paylood_ed25519: your private key
• ~/.ssh/paylood_ed25519.pub: your public key

Step 2: Install the public key on your VPS

Copy your public key to your VPS:

# Automatic method:
ssh-copy-id -i ~/.ssh/paylood_ed25519.pub root@YOUR_VPS_IP

# Or manual one-liner:
cat ~/.ssh/paylood_ed25519.pub | ssh root@YOUR_VPS_IP "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

Step 3: Update the server in Paylood

1. Display your private key:

   cat ~/.ssh/paylood_ed25519

2. Copy the entire text block (including -----BEGIN OPENSSH PRIVATE KEY----- and -----END OPENSSH PRIVATE KEY-----).
3. In Paylood, go to Servers and click Edit on your server card.
4. Under the Private Key tab, paste the private key.
5. Click Test Connection to verify, then Update Server.
6. Retry your application deployment.

Troubleshooting failed connections