DEV Community

Peon Sh
Peon Sh

Posted on

How to Deploy a Full-Stack App on a VPS with Peon

#ai #webdev #programming #productivity

Deploying a full-stack application on a VPS gives you control over your infrastructure without locking your application into a managed cloud platform. You can run your frontend, backend, database, and supporting services on your own Linux server while keeping your hosting costs predictable.

How to Deploy a Full-Stack App on a VPS with Peon

The challenge is that traditional VPS deployment often involves configuring SSH access, Docker, reverse proxies, SSL certificates, domains, environment variables, and deployment scripts manually.

Peon simplifies this workflow. It connects to your own Linux server over SSH, provisions the deployment environment, and lets you deploy applications from Git with a streamlined developer experience.

In this guide, you'll learn how to deploy a full-stack application on a VPS using Git, Docker, Nixpacks, Traefik, and Peon, including domain configuration, HTTPS, environment variables, and automatic deployments.

What You'll Build

By the end of this guide, you'll have a deployment architecture similar to:

GitHub Repository
       |
       v
      Peon
       |
       v
    Your VPS
       |
       +----------------+
       |                |
       v                v
   Frontend          Backend
       |                |
       +-------+--------+
               |
               v
            Database

       |
       v
    Traefik
       |
       v
   HTTPS Domain
Enter fullscreen mode Exit fullscreen mode

The exact services in your stack can vary. A full-stack application might include a Next.js frontend, Node.js API, PostgreSQL database, background workers, or other services.

Peon runs these applications on your server, rather than moving your application into a separate hosting environment.

What You Need Before You Start

You'll need the following:

On Your Local Machine

  • Git
  • An SSH client
  • A GitHub account
  • Your application repository
  • An SSH key pair

On Your Server

  • A Linux VPS
  • At least 1 GB RAM for a small application
  • A public IPv4 address
  • SSH access
  • A domain name if you want to use a custom domain

You can use a VPS from providers such as DigitalOcean or another Linux VPS provider.

On Peon

You'll need a Peon workspace. You can use Peon Cloud or self-host the Peon control plane.

The important distinction is that your application runs on your VPS. Peon connects to the server and manages the deployment workflow.

Step 1 — Prepare Your Full-Stack Application

Before deploying, make sure your application works locally.

A typical project might look like:

my-fullstack-app/
├── frontend/
├── backend/
├── package.json
├── docker-compose.yml
└── README.md
Enter fullscreen mode Exit fullscreen mode

For example, you could have:

  • React or Next.js for the frontend
  • Node.js for the backend
  • PostgreSQL for the database

Your application should also have a production build process.

For example:

npm install
npm run build
npm start
Enter fullscreen mode Exit fullscreen mode

The commands will depend on your framework.

If your project already uses Docker, you can deploy your existing configuration. If not, Peon can use Nixpacks to detect the application and create the required build environment without requiring you to manually write a Dockerfile.

Step 2 — Push Your Application to GitHub

Peon can deploy applications directly from Git repositories.

If your application isn't already in Git, initialize the repository:

git init
git branch -M main
git add .
git commit -m "Initial application"
Enter fullscreen mode Exit fullscreen mode

Create a repository on GitHub and connect it:

git remote add origin https://github.com/YOUR_USER/YOUR_REPOSITORY.git
git push -u origin main
Enter fullscreen mode Exit fullscreen mode

Your production deployment will use this repository as the source.

This also makes it possible to implement a simple push-to-deploy workflow later.

Step 3 — Create Your VPS

Next, provision a Linux VPS.

For a small application, a server with at least 1 GB RAM can be a starting point, although your actual requirements depend on the application, database, traffic, and number of services.

For example, when creating a DigitalOcean Droplet:

  1. Open DigitalOcean.
  2. Create a new Droplet.
  3. Select an Ubuntu LTS image.
  4. Choose your region.
  5. Select an appropriate server size.
  6. Add your SSH public key.
  7. Create the Droplet.
  8. Copy the server's public IPv4 address.

You can use another VPS provider as well. Peon is designed to work with Linux servers you control.

Step 4 — Create an SSH Key

Peon connects to your VPS using SSH.

If you don't already have a dedicated deployment key, create one:

ssh-keygen -t ed25519 -C "peon-deployment" -f ~/.ssh/peon_deployment
Enter fullscreen mode Exit fullscreen mode

This creates two files:

~/.ssh/peon_deployment
~/.ssh/peon_deployment.pub
Enter fullscreen mode Exit fullscreen mode

The .pub file contains your public key.

The file without .pub is your private key.

Never commit the private key to GitHub or include it in your application repository.

You can test the key against your VPS:

ssh -i ~/.ssh/peon_deployment root@YOUR_SERVER_IP
Enter fullscreen mode Exit fullscreen mode

If you can connect successfully, your SSH configuration is ready.

Step 5 — Add Your SSH Key to Peon

Now connect Peon to your server.

In your Peon dashboard:

  1. Open Keys & Tokens.
  2. Add a new SSH/private key.
  3. Paste your private SSH key.
  4. Give the key a recognizable name.
  5. Save it.

Your private key should retain its original formatting.

It should start with:

-----BEGIN OPENSSH PRIVATE KEY-----
Enter fullscreen mode Exit fullscreen mode

and end with:

-----END OPENSSH PRIVATE KEY-----
Enter fullscreen mode Exit fullscreen mode

Keep the line breaks intact.

The private key should never be stored in your Git repository.

Step 6 — Add Your VPS to Peon

Once your SSH key is available, add the server.

Go to:

Servers → Add/Create Server

Enter your server details:

Setting Example
Name my-production-server
IP / Hostname Your VPS IP
Port 22
User root
SSH Key Your Peon SSH key
Gateway Traefik

The SSH host key fingerprint can generally be left blank if you want Peon to record it automatically during the initial connection.

Save the server and select Connect to server.

Peon will validate the connection and provision the server.

Wait until the server status shows:

Online

Once the server is online, Peon can use it as your application deployment target.

Step 7 — Connect GitHub to Peon

Next, connect your Git repository.

In Peon:

  1. Open Git Sources.
  2. Select GitHub App.
  3. Connect your GitHub account or organization.
  4. Install the Peon GitHub App.
  5. Grant access to the repository containing your application.

You can restrict access to specific repositories if you don't want the GitHub App to access your entire account.

After connecting GitHub, your application repository should be available when creating a new service.

Step 8 — Create an Application Service

Now create the application that will run on your VPS.

Select:

New Service → Application (Git)

Choose:

  • Your GitHub source
  • Your repository
  • Your branch
  • Your target server

For example:

Repository: my-fullstack-app
Branch: main
Server: my-production-server
Enter fullscreen mode Exit fullscreen mode

Peon will use the repository as the source for your deployment.

For applications supported by Nixpacks, you don't necessarily need to manually create a Dockerfile.

Nixpacks can detect the application, determine the required runtime, install dependencies, and create the build environment.

Step 9 — Configure Environment Variables

Production applications commonly require environment variables for things such as:

  • Database connections
  • API keys
  • Authentication secrets
  • Application URLs
  • Runtime configuration

For example:

NODE_ENV=production
PORT=3000
NIXPACKS_NODE_VERSION=22
Enter fullscreen mode Exit fullscreen mode

If your backend uses PostgreSQL, you might also have:

DATABASE_URL=your-production-database-url
Enter fullscreen mode Exit fullscreen mode

Never hard-code production secrets into your source code.

Keep sensitive configuration in Peon's environment configuration rather than committing it to Git.

Step 10 — Configure Your Domain

Once the application is configured, add your production domain.

For example:

app.example.com
Enter fullscreen mode Exit fullscreen mode

In your DNS provider, create an A record pointing your domain to the VPS IP address.

For example:

Type: A
Name: app
Value: YOUR_SERVER_IP
Enter fullscreen mode Exit fullscreen mode

If your application uses separate frontend and API domains, you could configure:

app.example.com
api.example.com
Enter fullscreen mode Exit fullscreen mode

Point both records to the VPS and configure the appropriate services in Peon.

Step 11 — Deploy the Application

Once your server, Git repository, environment variables, and domain are configured, you're ready to deploy.

Open your application service and click:

Deploy

Peon will pull your source code and start the deployment process.

For a Nixpacks-based application, Nixpacks can handle the build environment without requiring you to manually create a Dockerfile.

The general workflow looks like:

GitHub
   |
   v
Peon
   |
   v
Nixpacks Build
   |
   v
Application Container
   |
   v
Your VPS
Enter fullscreen mode Exit fullscreen mode

Once deployment finishes, check the service logs to make sure the application started correctly.

Step 12 — Configure HTTPS

Your production application should use HTTPS.

Peon can use Traefik as the gateway to route incoming traffic to your applications and handle HTTPS configuration.

The request flow becomes:

User
 |
 | HTTPS
 v
Your Domain
 |
 v
Traefik
 |
 v
Application
Enter fullscreen mode Exit fullscreen mode

This means you don't need to manually configure a separate reverse proxy for every application.

Your domain should be accessible over HTTPS once DNS and the deployment configuration are correctly set up.

Step 13 — Enable Automatic Deployments

One of the biggest benefits of deploying from Git is that you can automate future releases.

In your Peon service, go to:

Configuration → Advanced

Enable:

Auto Deploy

Now your deployment workflow becomes:

Developer
    |
    v
Git Commit
    |
    v
git push
    |
    v
GitHub
    |
    v
Peon
    |
    v
Build
    |
    v
Deploy
Enter fullscreen mode Exit fullscreen mode

For example:

git add .
git commit -m "Update application"
git push origin main
Enter fullscreen mode Exit fullscreen mode

Once the push reaches GitHub, Peon can trigger a new deployment.

This eliminates the need to SSH into the VPS and manually pull the latest code every time you release an update.

Step 14 — Test Your Deployment

After the first deployment, perform a basic production smoke test.

Test the Website

Open your domain:

https://app.example.com
Enter fullscreen mode Exit fullscreen mode

Make sure the frontend loads correctly.

Test the API

If your application has an API, test an endpoint such as:

https://api.example.com/health
Enter fullscreen mode Exit fullscreen mode

You should receive the expected response.

Test the Database

Verify that your backend can:

  • Connect to the database
  • Read data
  • Write data
  • Run required migrations

Test Automatic Deployment

Make a small change:

git add .
git commit -m "Test automatic deployment"
git push origin main
Enter fullscreen mode Exit fullscreen mode

Then check the Peon deployment activity.

The new commit should trigger a deployment if Auto Deploy is enabled.

Deploying Multiple Services on One VPS

One of the advantages of using a VPS is that you can run multiple services on the same server, assuming the server has enough resources.

For example:

VPS
 |
 +-- Application 1
 |
 +-- Application 2
 |
 +-- API
 |
 +-- PostgreSQL
 |
 +-- Redis
 |
 +-- Worker
Enter fullscreen mode Exit fullscreen mode

Traefik can route different domains or subdomains to the appropriate services.

For example:

app.example.com  → Frontend
api.example.com  → Backend
admin.example.com → Admin App
Enter fullscreen mode Exit fullscreen mode

This gives you considerably more control over your infrastructure than simply deploying each application independently to a separate managed platform.

Common Full-Stack VPS Deployment Problems

The Domain Doesn't Open

Check:

  • DNS A record
  • VPS IP address
  • Domain configuration
  • Server status
  • Gateway configuration

DNS changes can also take time to propagate.

The Application Builds but Doesn't Start

Check the deployment logs.

Common causes include:

  • Incorrect start command
  • Missing environment variables
  • Unsupported runtime version
  • Application listening on the wrong port
  • Missing production dependencies

The Backend Cannot Connect to the Database

Verify your database connection string and make sure the database service is accessible from the application.

Also check whether your application expects localhost when the database actually runs as another container or service.

HTTPS Isn't Working

Check:

  • DNS configuration
  • Domain configuration
  • Gateway configuration
  • Port 80/443 accessibility
  • SSL certificate provisioning

Deployment Isn't Triggering

If Git pushes aren't creating deployments, check:

  • GitHub connection
  • Repository permissions
  • Selected branch
  • Auto Deploy setting
  • Webhook/application integration

VPS Deployment Security Checklist

Before putting your application into production, review your server security.

  • Use SSH keys
  • Avoid exposing unnecessary ports
  • Configure a firewall
  • Keep the operating system updated
  • Keep application dependencies updated
  • Use HTTPS
  • Protect production secrets
  • Don't commit private keys to Git
  • Restrict database access
  • Back up important data
  • Monitor server resources
  • Keep application logs available
  • Have a rollback or recovery plan

Self-hosting gives you more control, but it also means you have responsibility for the security and maintenance of your infrastructure.

Why Use Peon for VPS Deployment?

A traditional VPS deployment can require you to manually configure:

  • SSH
  • Docker
  • Reverse proxies
  • SSL
  • Domains
  • Git deployments
  • Environment variables
  • Application processes
  • Deployment scripts

Peon brings these deployment workflows into one platform while allowing your applications to run on your own infrastructure.

You keep control of the server while getting a more convenient deployment workflow:

Connect your server → connect Git → configure your application → deploy.

You can also enable automatic deployments so that Git pushes become application releases.

For developers looking for a more controlled alternative to fully managed deployment platforms, this provides a practical middle ground between manually managing a VPS and handing the entire infrastructure over to a cloud platform.

Final Thoughts

Deploying a full-stack application on a VPS doesn't have to mean manually managing every part of your infrastructure.

With a Linux VPS, Git, Nixpacks, Traefik, and Peon, you can build a deployment workflow that gives you control over your infrastructure while keeping the developer experience simple.

The basic workflow is:

Build Your App
      ↓
Push to GitHub
      ↓
Connect GitHub to Peon
      ↓
Connect Your VPS
      ↓
Configure Environment
      ↓
Add Your Domain
      ↓
Deploy
      ↓
Enable Auto Deploy
Enter fullscreen mode Exit fullscreen mode

Your application stays on your server, while Peon handles the deployment workflow around it.

If you want to deploy applications on your own infrastructure without manually configuring every deployment step, Peon provides an open-source deployment platform with a simple Git-based workflow.

Deploy Your Apps on Your Own Server

Peon lets you deploy applications to your own Linux servers with Git-based deployments, automatic HTTPS, databases, and deployment automation.

Start deploying for $3 per project or self-host Peon for free.

Related Articles

Top comments (0)