How to Install and Run PortNote on Debian VPS

This article provides a guide for how to install and run PortNote on Debian VPS.

What is PortNote?

PortNote gives you a clear, organized view of your entire port landscape. Add your servers and VMs via a sleek web interface, assign and document port usage across all systems, and avoid conflicts before they happen. PortNote brings structure, clarity, and control to one of the most overlooked parts of your infrastructure.

📋 Prerequisites

• A Debian 11 or Debian 12 VPS with root access
• Domain name (optional, but recommended for HTTPS)
• Basic command-line knowledge
• Docker and Docker Compose (PortNote is containerized)

🛠️ How to Install and Run PortNote on Debian VPS (Self-Hosted)

To install and run PortNote on Debian VPS, follow the steps below:

1. 🔐 Update and Secure Your VPS

   sudo apt update && sudo apt upgrade -y

   Optionally, add a firewall like ufw:

   sudo apt install ufw -y sudo ufw allow ssh sudo ufw enable

2. 🐳 Install Docker & Docker Compose

   Install Docker:

   curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh

   Install Docker Compose (v2):

   sudo apt install docker-compose-plugin -y

   Verify:

   docker --version docker compose version

3. 📦 Configure Docker Compose

   Edit docker-compose.yml:

   services:   web:     image: haedlessdev/portnote:latest     ports:       - "3000:3000"     environment:       JWT_SECRET: RANDOM_SECRET # Replace with a secure random string       USER_SECRET: RANDOM_SECRET # Replace with a secure random string       LOGIN_USERNAME: username # Replace with a username       LOGIN_PASSWORD: mypassword # Replace with a custom password       DATABASE_URL: "postgresql://postgres:postgres@db:5432/postgres"     depends_on:       db:         condition: service_started   agent:     image: haedlessdev/portnote-agent:latest     environment:       DATABASE_URL: "postgresql://postgres:postgres@db:5432/postgres"     depends_on:       db:         condition: service_started   db:     image: postgres:17     restart: always     environment:       POSTGRES_USER: postgres       POSTGRES_PASSWORD: postgres       POSTGRES_DB: postgres     volumes:       - postgres_data:/var/lib/postgresql/data volumes:   postgres_data:

4. ⚙️ Configure .env File

   Make a copy of the example environment:

   cp .env.example .env

   Edit the .env file to set the admin email, domain, and optionally change the database password and JWT secret:

   nano .env

   Key variables to customize:

   JWT_SECRET: RANDOM_SECRET # Replace with a secure random string USER_SECRET: RANDOM_SECRET # Replace with a secure random string LOGIN_USERNAME: username # Replace with a username LOGIN_PASSWORD: mypassword # Replace with a custom password

5. 🔧 Configure Reverse Proxy (Optional for Custom Domain)

   If using a custom domain, it’s best to enable HTTPS with a reverse proxy like Nginx and Let’s Encrypt.

   You can use Nginx Proxy Manager or set up your own Nginx + Certbot manually.

   Otherwise, skip to the next step to run it on localhost with port binding.

6. 🚀 Launch PortNote with Docker Compose

   Make sure you’re in the root portnote/ folder:

   docker compose up -d

   Wait for containers to initialize. You can check logs with:

   docker compose logs -f

7. 🧪 Access PortNote

   • If using a domain:
   • Visit http://yourdomain.com
   • If using localhost or IP:
   • Visit http://YOUR_SERVER_IP:3000

   

8. 🔄 Optional: Set Up System Auto-Start

   To ensure PortNote starts on reboot:

   sudo systemctl enable docker.service sudo systemctl enable containerd.service

   If you’re using a custom Docker Compose service script, you can enable it as a systemd service.

9.  (Optional) Configure Backups

   To back up your PortNote data:

   docker exec -it portnote-db pg_dump -U postgres portnote > portnote_backup.sql

   Store this securely or use remote backup automation.

🔚 Done!

Your self-hosted PortNote instance is now live and secured.

📎 Helpful Commands

# Stop the app
docker compose down
# Restart the app
docker compose up -d
# View running containers
docker ps

🔐 Security Tips

• Change default JWT and DB secrets
• Keep VPS and Docker updated
• Set up a firewall and fail2ban
• Use HTTPS with a trusted certificate

Secure PortNote with Free SSL Certificate

To install and secure PortNote with free SSL certificate, follow the steps below:

1. Install Nginx and Certbot:

   sudo apt update sudo apt install nginx certbot python3-certbot-nginx -y

2. Configure Ngnix:

   sudo nano /etc/nginx/sites-available/portnote

   Enter the following:

   server { listen 80; server_name portnote.raddemo.host; location / { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; } }

3. Enable the site:

   sudo ln -s /etc/nginx/sites-available/portnote /etc/nginx/sites-enabled/

4. Test and reload:

   sudo nginx -t sudo systemctl reload nginx

5. Request the SSL using Certbot:

   sudo certbot --nginx -d portnote.raddemo.host

   Output:

   root@portnote:~# sudo certbot --nginx -d portnote.raddemo.host Saving debug log to /var/log/letsencrypt/letsencrypt.log Plugins selected: Authenticator nginx, Installer nginx Enter email address (used for urgent renewal and security notices) (Enter 'c' to cancel): xxxxxxxx@xxxxxxx.xxxx - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Please read the Terms of Service at https://letsencrypt.org/documents/LE-SA-v1.5-February-24-2025.pdf. You must agree in order to register with the ACME server. Do you agree? - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - (Y)es/(N)o: Y - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Would you be willing, once your first certificate is successfully issued, to share your email address with the Electronic Frontier Foundation, a founding partner of the Let's Encrypt project and the non-profit organization that develops Certbot? We'd like to send you email about our work encrypting the web, EFF news, campaigns, and ways to support digital freedom. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - (Y)es/(N)o: n Account registered. Requesting a certificate for portnote.raddemo.host Performing the following challenges: http-01 challenge for portnote.raddemo.host Waiting for verification... Cleaning up challenges Deploying Certificate to VirtualHost /etc/nginx/sites-enabled/portnote Redirecting all traffic on port 80 to ssl in /etc/nginx/sites-enabled/portnote - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Congratulations! You have successfully enabled https://portnote.raddemo.host - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - IMPORTANT NOTES: - Congratulations! Your certificate and chain have been saved at: /etc/letsencrypt/live/portnote.raddemo.host/fullchain.pem Your key file has been saved at: /etc/letsencrypt/live/portnote.raddemo.host/privkey.pem Your certificate will expire on 2025-09-27. To obtain a new or tweaked version of this certificate in the future, simply run certbot again with the "certonly" option. To non-interactively renew *all* of your certificates, run "certbot renew" - If you like Certbot, please consider supporting our work by: Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate Donating to EFF: https://eff.org/donate-le root@portnote:~#

6. Enable Auto-Renewal (Optional):
   Certbot adds this automatically via systemd timer, but you can test it with:

   sudo certbot renew --dry-run

7. Access PortNote Securely:

   https://portnote.raddemo.host

   You should see your PortNote login screen, served securely via HTTPS.

🧰 Nginx + Certbot Reference Commands

Conclusion

You now know how to install and run PortNote on Debian VPS. You also learned how to install and secure PortNote with free SSL certificate.