DocsMigration Guide

Migration Guide

Bring Your Existing Applications Into Klystrr

If you already have applications running on a VPS — managed with PM2, served through Nginx or Apache, secured with SSL, and pointed at custom domains — Klystrr lets you import them without touching what is already working.

Overview

100% read-only

The scan writes nothing to your server. Your application keeps running exactly as before.

Runtime monitoring

Display live PM2 status, port, domain, and SSL — without configuring deployments.

Deployments when ready

Connect your Git repository and complete deployment config at your own pace.

Who This Guide Is For

This guide is for developers who already have one or more applications running on a VPS and want to bring them under Klystrr management without disrupting their current setup.

You are likely in this situation if you have:

A Node.js, NestJS, React, Next.js, or Vite application running in production
A PM2 process managing your application
Nginx or Apache configured as a reverse proxy
A domain already pointed at your application
SSL certificates active on the server (Certbot, Let's Encrypt, or manual)
A Git repository cloned somewhere on the server
Environment variables or a .env file your application depends on

You do not need all of these for an import to work. Klystrr will detect what it can and let you fill in the rest manually.

Before You Start

Make sure the following are in place before beginning an import.

Your VPS is already connected to Klystrr

The server must appear in your Klystrr server list with a working SSH connection.

SSH access is functional

Klystrr needs to be able to connect to the server to run the scan.

PM2 is installed on the server

If your application uses PM2 for process management.

Nginx or Apache is installed

If your application is served through a reverse proxy.

Git is installed on the server

If the application was deployed from a repository.

You have access to your DNS provider

If domains are part of the setup and you plan to manage them.

You have access to your GitHub or GitLab account

If you want Klystrr to manage future deployments of this application.

You are responsible for your own server, its configuration, credentials, application files, domain settings, and secrets. Klystrr operates on the information it can read from your server and does not take responsibility for pre-existing misconfiguration.

Safe Import Mode

Safe Import is Klystrr's default import flow. It is entirely read-only. During a Safe Import, Klystrr scans your server to build a picture of what is running. It does not make any changes.

Specifically, Klystrr does NOT:

×Restart or stop any PM2 process

×Modify any Nginx or Apache configuration file

×Regenerate or revoke SSL certificates

×Delete, move, or overwrite any application files

×Redeploy the application

×Automatically link a detected Git repository to the Klystrr project

The scan reads system state and configuration. Your application continues running exactly as it was before, during, and after the scan.

What Klystrr Detects

The scan attempts to detect the following information from your server. Detection may be partial depending on your server configuration, file permissions, and installed tools.

PM2 processes

—Process name and PM2 identifier
—Application root path
—Internal port the process listens on
—Process status (online, stopped, errored)
—Restart count and uptime

Web server configuration

—Nginx virtual host files and server blocks
—Apache virtual host configuration
—Configured server names and domain names
—Proxy pass targets and upstream ports

SSL certificates

—Whether SSL is active on detected domains
—Certificate presence and approximate expiry (where readable)

Git metadata (informational only)

—Remote URL of the cloned repository
—Current branch
—Most recent commit hash

Even if Klystrr detects that your application was cloned from a repository, you still need to explicitly connect that repository through the Klystrr Git provider integration. This is required for security and OAuth permission verification.

Environment variables

—Whether a .env file is present on the server
—Environment variable key names (keys only — values are never read or stored)

Import Steps

Select an existing server

Open your server list in Klystrr and select the server where the application is running. Confirm that the SSH connection is active.

Run a safe scan

Trigger the scan from the server detail page. Klystrr connects over SSH and inspects PM2, Nginx, Apache, SSL, Git metadata, and filesystem paths. The scan runs in the background and does not affect running processes.

Review detected applications

Once the scan completes, Klystrr displays a list of applications it detected on the server. Each detected application shows the information collected: process name, path, port, domain, and status.

Select the application to import

Choose the application you want to bring into Klystrr. If an application was not detected automatically, you can enter its details manually.

Confirm detected details

Review the information Klystrr collected. Correct anything that was detected incorrectly or is incomplete. Confirm the application path, port, domain, and PM2 process name.

Create or link a Klystrr project

Assign the imported application to a new Klystrr project or link it to an existing one. This is the record Klystrr uses to track the application going forward.

Review missing configuration

Klystrr shows you which parts of the deployment configuration are missing: Git repository connection, build and start commands, environment variables. You do not need to complete these immediately.

Enable runtime monitoring if desired

Once imported, you can enable runtime monitoring. This allows Klystrr to display live PM2 status, port, domain reachability, and SSL state. Enabling runtime monitoring does not modify anything on the server.

Complete deployment setup when ready

When you are ready for Klystrr to manage future deployments, complete the full deployment configuration: connecting your Git repository, confirming build commands, and adding environment variables.

Imported App vs Runtime-Managed App vs Deployment-Ready App

Understanding these three states prevents confusion about what Klystrr can and cannot do at each stage.

Imported App

—The application is visible in Klystrr and linked to a server
—Existing PM2 processes, Nginx/Apache configuration, SSL, and domain setup remain untouched
—Klystrr has a record of the application but does not control it
—No deployment management is active

Runtime-Managed App

—Klystrr can display live runtime information
—PM2 status, detected port, domain, SSL state, and server path are visible in the dashboard
—Klystrr may surface alerts if the PM2 process goes offline
—The application is still not deployable through Klystrr

Runtime management does not mean deployment is ready. An application can be fully monitored by Klystrr and still not be ready for redeployment.

Deployment-Ready App

—Git repository connected through Klystrr's Git provider integration
—Branch selected
—Install, build, and start commands confirmed
—Environment variables added
—Application path confirmed
—PM2 process name confirmed
—Internal port confirmed
—Domain confirmed

Deployment Readiness Checklist

Before Klystrr enables the Deploy/Redeploy action, the following must be in place. The Deploy button is intentionally disabled until the required configuration is complete.

Server connected and SSH verified

Application imported into a Klystrr project

PM2 process detected or manually configured

Internal port detected or manually configured

Domain detected or manually configured

SSL status reviewed

Git repository connected through Klystrr

Target branch selected

Install command configured (e.g. npm install)

Build command configured if applicable (e.g. npm run build)

Start command or entry point confirmed

Environment variables added or confirmed

Deployment path confirmed

Environment Variables and Secrets

During the scan, Klystrr may detect that a .env file is present on the server. It reads only the key names — never the values.

DATABASE_URL = ••••••••

JWT_SECRET = ••••••••

API_KEY = ••••••••

Klystrr shows detected variable keys with masked values in the dashboard.

To enable future deployments through Klystrr, you will need to re-enter the values for any environment variables your application requires.

Klystrr stores these securely for use during the deployment process.

Do not share secrets in plain text, in logs, or in support requests. Klystrr never logs environment variable values.

Domains & DNS

Klystrr may detect domain names from your Nginx or Apache configuration. Detection is based on reading server_name directives in Nginx or ServerName and ServerAlias directives in Apache.

DNS must point to the correct server

Klystrr reads configuration from the server but does not control your DNS provider.

DNS propagation takes time

Changes to DNS records can take minutes to hours to propagate globally. Klystrr cannot accelerate this.

Custom domains may require verification

Depending on your setup.

Klystrr does not automatically manage external DNS

Unless a DNS provider integration is configured separately.

Applications Behind Cloudflare

Cloudflare IPs in DNS lookups

When Cloudflare proxy is active (orange cloud), DNS lookups for your domain return Cloudflare IP addresses, not your VPS IP. This is expected behavior. Klystrr uses the server IP it already knows from your VPS connection, not the DNS lookup result.

SSL mode

If SSL certificates exist on your origin server, set the Cloudflare SSL/TLS mode to Full or preferably Full (strict). Using Flexible mode with an origin certificate can cause redirect loops or inconsistent behavior.

Certbot and HTTP-01 challenges

Certbot's HTTP-01 challenge may fail if Cloudflare is proxying traffic and has rules that interfere with the /.well-known/acme-challenge/ path. If this occurs, temporarily set the DNS record to DNS only during certificate issuance, then re-enable the proxy afterward.

Current Cloudflare support

Klystrr detects that a domain is using Cloudflare based on IP ranges and headers. Direct Cloudflare API integration for automated DNS or certificate management is not currently available. This may change in a future release.

Common Migration Scenarios

Import a PM2 app with an existing Nginx reverse proxy

The most common scenario. Klystrr detects the PM2 process, reads the Nginx server block, identifies the domain and upstream port, and checks SSL. After import, the application is visible in Klystrr. Connect your Git repository and configure deployment commands when you are ready.

Import a PM2 app with an Apache VirtualHost

The flow is the same as with Nginx. Klystrr reads the Apache VirtualHost file, detects the domain and proxy configuration, and checks for SSL. Apache configuration parsing depends on standard ProxyPass and ProxyPassReverse directives.

Import an app without a domain

If your application runs on a bare port with no domain configured, Klystrr will detect the PM2 process and the listening port. Domain and SSL detection will show as not configured. You can add a domain later through Klystrr.

Import an app without Git metadata

If the application was deployed manually without cloning a Git repository, Klystrr will not detect any Git metadata. This is expected. You can still import the application — deployment management through Klystrr requires a connected Git repository added afterward.

Import an app behind Cloudflare

Import works normally. Klystrr reads your server configuration directly over SSH and does not rely on public DNS. SSL detection reads the origin certificate directly, not through the Cloudflare proxy. Be aware of the SSL mode and challenge limitations.

Import an app with existing SSL

Klystrr detects whether SSL certificates are present on the server. It does not modify, renew, or revoke existing certificates during import. If you later redeploy through Klystrr, SSL configuration will be part of the deployment setup.

Troubleshooting

Click an issue to expand the diagnosis and solutions.

Safety Recommendations

Before and during migration, follow these practices to avoid disrupting your running application.

Do not delete existing application files until you have confirmed that the import is complete and you understand what will happen during a Klystrr-managed deployment.

Do not switch to Klystrr deployment management until you have reviewed all deployment commands and verified that they match how your application was originally built.

Back up critical application files and data before making any changes to the server.

Back up your Nginx or Apache configuration before modifying it.

Verify that your install, build, and start commands are correct before triggering a deployment through Klystrr. A misconfigured build command can overwrite or break your running application.

Keep SSH credentials and private keys secure. Do not share them or store them in version control.

Do not expose secrets or environment variable values in logs, support requests, or configuration files that are committed to Git.

Review DNS and SSL configuration before switching traffic to a Klystrr-managed deployment.

FAQ

Ready to Import Your Application?

If your VPS is already connected to Klystrr, you can start a scan from the server detail page right now. Your application keeps running throughout this process.