How to connect your GitHub account and deploy your first Next.js app to your VPS

Table of Contents

1. Prerequisites

2. Understanding the Setup

3. Step 1: Connect Your GitHub Account

4. Step 2: Deploy Your Next.js Application

5. Step 3: Enable Auto-Deploy (Optional)

6. Troubleshooting

7. What's Happening Behind the Scenes

Prerequisites

Before you begin, make sure you have:

• ✅ A VPS (Virtual Private Server) added to ServerCompass

• ✅ SSH access to your VPS (ServerCompass manages this for you)

• ✅ A GitHub account with a Next.js repository

• ✅ Basic understanding of Git and GitHub

You can view the tutorial video at https://www.youtube.com/watch?v=xphfiIBpc0o

Understanding the Setup

ServerCompass uses a secure, SSH-based authentication system to connect your VPS to GitHub. Here's what makes it special:

• 🔐 Secure: Your GitHub credentials are encrypted using AES-256-GCM encryption

• 🎯 Multi-Account Support: Connect multiple GitHub accounts (personal, work, clients) to the same VPS

• 🤖 Automated: SSH keys are automatically configured and uploaded to GitHub

• ♻️ Reusable: Once connected, deploy unlimited projects from that GitHub account

Step 1: Connect Your GitHub Account

1.1 Navigate to Git Settings

1. Open ServerCompass

2. Select your VPS from the servers list

3. Go to the "Git" tab

4. Click "Connect GitHub Account"

1.2 Choose or Create an SSH Key

ServerCompass will show you a list of SSH keys available on your VPS (from ~/.ssh/).

Option A: Use an Existing Key

• Select an existing key like id_ed25519.pub or id_rsa.pub

• Make sure you have the private key pair on your server

Option B: Create a New Key

• ServerCompass can generate a new SSH key pair for you

• This is recommended if you want to separate GitHub access from other SSH connections

💡 Tip: If you're unsure, create a new key. ServerCompass handles everything automatically!

1.3 Create a GitHub Personal Access Token

Now you need to create a Personal Access Token (PAT) to allow ServerCompass to manage your GitHub account:

1. ServerCompass will display a direct link: https://github.com/settings/tokens/new

2. Click "Generate new token" → "Generate new token (classic)"

3. Give it a descriptive name: ServerCompass - MyVPS

4. ⚠️ IMPORTANT: Select these scopes:

   • ✅ repo - Full control of private repositories

   • ✅ admin:public_key - Access to manage deploy keys

   • ✅ read:org - Read organization memberships (if deploying org repos)

5. Click "Generate token" at the bottom

6. Copy the token (you'll only see it once!)

1.4 Complete the Connection

1. Paste the token into ServerCompass

2. Give your connection a friendly name (e.g., "Personal GitHub" or "Work Account")

3. Click "Connect"

What happens now:

• ✅ ServerCompass validates your token and checks the scopes

• ✅ Your public SSH key is uploaded to your GitHub account

• ✅ SSH configuration is created on your VPS (in ~/.ssh/config)

• ✅ The token is encrypted and stored securely

• ✅ Connection is tested automatically

You should see: ✅ "Successfully connected to GitHub as @yourusername"

Step 2: Deploy Your Next.js Application

Now comes the fun part – deploying your app!

2.1 Start a New Deployment

1. Navigate to the "Apps" tab on your server

2. Click "Deploy New Service"

3. Select "Node.js" as the runtime

2.2 Select Your Repository

1. Choose the GitHub account you just connected

2. ServerCompass will fetch all your repositories

3. Search or browse for your Next.js project

4. Select the repository and branch (usually main or master)

2.3 Configure Your Application

ServerCompass will automatically detect your Next.js setup! Here's what it finds:

Automatic Detection:

• 🔍 Framework: Next.js

• 📦 Package Manager: npm, yarn, pnpm, or bun

• 🏗️ Build Command: npm install && npm run build

• 🚀 Start Command: npm start

• 🔌 Port: Usually 3000 (from your package.json)

You can customize:

1. Application Name: Choose a memorable name (e.g., my-blog)

2. Port: Change if you need a different port (default: 3000)

3. Environment Variables: Add any .env variables your app needs

   Example:

   DATABASE_URL=postgresql://user:pass@host/db
   NEXT_PUBLIC_API_URL=https://api.mysite.com
   API_SECRET_KEY=your-secret-key

4. Build Command: Usually fine as-is, but you can customize

5. Start Command: For production Next.js apps, use npm start

💡 Note: You don't need to add PORT or NODE_ENV to environment variables – ServerCompass handles these automatically!

2.4 Deploy!

1. Review your configuration

2. Click "Deploy"

3. Watch the magic happen in real-time! 🎉

Deployment Progress:

You'll see live logs of each step:

✓ Checking server prerequisites...
✓ Installing Node.js, npm, and PM2...
✓ Preparing deployment directory...
✓ Cloning repository from GitHub...
✓ Installing dependencies (npm install)...
✓ Building application (npm run build)...
✓ Starting application with PM2...
✓ Deployment completed successfully!

Deployment typically takes 2-5 minutes depending on your app's size and dependencies.

2.5 Access Your Application

Once deployed, your Next.js app is running!

• URL: http://your-vps-ip:3000 (or your custom port)

• Status: Check the Apps tab to see if it's running

• Logs: View real-time logs to debug any issues

• Management: Start, stop, restart, or redeploy anytime

Step 3: Enable Auto-Deploy (Optional)

Want your app to automatically update when you push to GitHub? Enable Auto-Deploy!

3.1 Enable Auto-Deploy

1. Go to your deployed app in the Apps tab

2. Click on the app to see details

3. Navigate to the "Deployments" section

4. Toggle "Auto-Deploy" to ON

3.2 Configure Polling

ServerCompass will ask:

• Branch to Monitor: Which branch to watch (e.g., main)

• Poll Interval: How often to check for updates (default: 60 seconds)

3.3 How It Works

ServerCompass sets up a cron job on your VPS that:

1. ⏰ Checks your GitHub repository every 60 seconds (or your chosen interval)

2. 🔍 Compares the latest commit hash with what's currently deployed

3. 📥 If there's a new commit, automatically pulls the latest code

4. 🏗️ Rebuilds your application

5. 🔄 Performs a zero-downtime restart using PM2

6. 📝 Logs everything to ~/servercompass/auto-deploy.log

Benefits:

• 🚀 Push to GitHub → Auto-deploy in ~1-2 minutes

• 🛡️ Zero-downtime deployments (users never see your app go down)

• 📊 Full deployment history and logs

• ⏸️ Easy to enable/disable anytime

Troubleshooting

Problem: "SSH Authentication Failed"

Solution:

• Verify your SSH key is uploaded to GitHub: github.com/settings/keys

• Look for a key named ServerCompass-{serverId}-{timestamp}

• If missing, reconnect your GitHub account

Problem: "Build Failed During npm run build"

Solution:

• Check the deployment logs for specific error messages

• Common issues:

  • Missing environment variables → Add them in the deployment config

  • Insufficient memory → Upgrade your VPS plan

  • TypeScript errors → Fix in your codebase and push again

Problem: "Port Already in Use"

Solution:

• Choose a different port (e.g., 3001, 3002)

• Or stop the conflicting application in the Apps tab

Problem: "Cannot Access Application After Deployment"

Solution:

• Check your VPS firewall settings – ensure your port is open

• Verify the app is running: Check status in Apps tab

• View logs for errors: Click on your app → Logs

Problem: "Token Scope Insufficient"

Solution:

• Your GitHub token is missing required scopes

• Regenerate token with repo, admin:public_key, and read:org scopes

• Reconnect your GitHub account with the new token

What's Happening Behind the Scenes

Understanding the technical details can help you troubleshoot and optimize your deployments.

SSH Configuration

When you connect a GitHub account, ServerCompass creates an entry in ~/.ssh/config:

Host github-yourusername
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
  AddKeysToAgent yes

This allows your VPS to authenticate with GitHub using your SSH key.

Repository Cloning

Your repository is cloned using SSH:

git clone git@github-yourusername:yourusername/your-nextjs-app.git

For updates (redeployments), ServerCompass runs:

cd /root/your-app-name
git fetch origin main
git checkout main
git pull origin main

Application Management with PM2

ServerCompass uses PM2 (Process Manager 2) to run your Next.js app:

# Initial deployment
PORT=3000 pm2 start "npm start" --name "my-nextjs-app"

Redeployment (zero-downtime)

pm2 reload my-nextjs-app

PM2 Benefits:

• ✅ Keeps your app running 24/7

• ✅ Auto-restarts if crashes occur

• ✅ Zero-downtime reloads

• ✅ Process monitoring and logs

• ✅ Auto-starts on server reboot

Security: Credential Encryption

Your GitHub token is never stored in plain text:

1. Token is encrypted using AES-256-GCM encryption

2. Master encryption key stored securely in <userData>/.vault_key

3. Encrypted token stored in SQLite database

4. Decrypted only when needed for Git operations

5. Never exposed to the renderer process or UI

Multi-Account Architecture

ServerCompass supports multiple GitHub accounts on one VPS:

• Each account has its own SSH key and configuration

• Accounts are isolated from each other

• Switch between accounts when deploying different projects

• Perfect for agencies managing client projects

Next Steps

Now that you've deployed your first Next.js app, here are some ideas:

1. 🌐 Set Up a Domain: Point a domain to your VPS IP for a proper URL

2. 🔒 Add SSL/TLS: Set up HTTPS with Let's Encrypt (ServerCompass can help!)

3. 📊 Monitor Performance: Check CPU, memory, and disk usage in ServerCompass

4. 🔄 Enable Auto-Deploy: Set it and forget it – push to GitHub and it deploys automatically

5. 🚀 Deploy More Apps: You can run multiple apps on different ports

Additional Resources

• ServerCompass Documentation: docs.servercompass.app

• GitHub SSH Keys Guide: docs.github.com/authentication

• Next.js Deployment Docs: nextjs.org/docs/deployment

• PM2 Documentation: pm2.keymetrics.io

Summary

You've learned how to:

✅ Connect your GitHub account to your VPS securely
✅ Deploy a Next.js application with automatic framework detection
✅ Configure environment variables and deployment settings
✅ Enable auto-deploy for continuous delivery
✅ Troubleshoot common deployment issues

ServerCompass makes VPS management accessible by automating the complex parts of server configuration, Git integration, and application deployment. What used to take hours of manual SSH commands and configuration now takes just a few clicks!

Happy deploying! 🚀

Have questions or feedback? Open an issue on GitHub or reach out to the community.