Migrate from v4

Overview

Surfly v5 introduces a new installation flow, a new configuration format, and updated runtime requirements. This guide covers two supported migration paths:

• In-place upgrade – reuse the existing host, upgrade dependencies, and install Surfly v5 over the previous deployment.
• Fresh install with data migration – provision a clean host, install v5, and migrate configuration, certificates, and data.

Choose the workflow that best fits your change window and ability to provision new infrastructure. Complete the shared preparation tasks before you start either path.

Preparation

This section covers all the necessary preparation before you start the migration. This includes understanding the changes in v5 and preparing your configuration and data.

Step 1: Review v5 Requirements and Changes

Complete these checks to confirm your environment can run Surfly v5.

Baseline requirements

Component	v4.x baseline	v5 requirement
Operating system	CentOS 9 Stream / RHEL 9	Any Linux distribution that supports required runtimes
Container runtime	Podman 4.x	Podman 5.4.0+
Service manager	Systemd 249+	Systemd 252+
Redis	Redis 6.2	Redis 6.2.18+
PostgreSQL	PostgreSQL 13–14	PostgreSQL 16 (mandatory)

See the system requirements page for the current hardware profile and supported dependencies.

File layout updates

Legacy v4.x installations relied on /opt/cobro for configuration and service definitions. Surfly v5 reorganises these assets:

• Runtime home: ~/surfly/
• Configuration file: ~/surfly/config.env
• Certificates: ~/surfly/certs/
• Error templates: ~/surfly/error_templates/
• Container units: ~/.config/containers/systemd/*.container
• Target units: ~/.config/systemd/user/ss-*.target

Review any automation or monitoring that references the old /opt/cobro structure and update paths accordingly.

Configuration changes

The legacy config.yaml is replaced by a dotenv-style config.env located in ~/surfly/config.env. Consult the configuration reference for the full variable list. Common mappings to review during migration:

Legacy key	New variable	Notes
client_id	CLIENT_ID	Required to pull builds and container images
client_secret	CLIENT_SECRET	Required to pull builds and container images
cobro_auth_token	COBRO_AUTH_TOKEN	Used by the Cobro API
dashboard_auth_token	DASHBOARD_AUTH_TOKEN	Used by the Dashboard API
rest_api_rate_limit	REST_API_RATE_LIMIT	Rate limiting in haproxy
allow_private_resources	ALLOW_PRIVATE_RESOURCES	Security posture for private targets
nginx_dns_resolvers	NGINX_DNS_RESOLVERS	Space-separated list of DNS resolvers
environment.redis_host / environment.redis_port	REDIS_HOST / REDIS_PORT	Redis connectivity
environment.db_connect_string	DB_CONNECT_STRING	Main database connection string
environment.dashboard_urls	DASHBOARD_URLS	Used in multi-server deployments
environment.default_login_sso	DEFAULT_LOGIN_SSO	Switch default login page

Note

The legacy environment: section is no longer nested. Each entry becomes its own uppercase variable (for example environment.redis_host → REDIS_HOST). Review every item you had under environment: and add its corresponding v5 variable to config.env.

Mandatory variables

Surfly v5 enforces several variables that may have been optional previously. Ensure these are defined before starting services:

• CLIENT_ID and CLIENT_SECRET – authenticate with the Surfly registry.
• SECRET_KEY – secures signed data in Dashboard and Studio; generate a new random value if you do not have one already.
• DASHBOARD_AUTH_TOKEN and COBRO_AUTH_TOKEN – required for internal API communication.

Set any other empty mandatory variables noted in the configuration reference according to your deployment requirements.

Step 2: Prepare Migration Assets

Perform these preparation steps once and use the results in either migration path.

Convert configuration to config.env

1. Export the existing /home/<user>/install/config.yaml.
2. Create a new ~/surfly/config.env and populate it with the required variables using the mappings above.
3. Cross-check every value against the configuration reference to ensure the syntax matches the new format (uppercase keys, KEY=value lines, quoted values only when needed).

Tip

When copying secrets, rotate long-lived tokens that were previously shared between environments. Surfly v5 isolates services and expects unique credentials per deployment.

Copy TLS Certificates

Copy your existing certificates from /opt/cobro/certs/ to a new Surfly certs location: ~/surfly/cert.

cp /opt/cobro/certs/* ~/surfly/certs/

Migrate Custom Templates

If you have customized error pages or other templates in v4, you need to adapt them to the v5 structure.

• In v4, templates were located in a single directory (e.g., /opt/cobro/proxy/app/templates).
• In v5, templates are managed per-service (HAProxy, Varnish, Proxy) and loaded from ~/surfly/error_templates/.
• Most of your old session-related templates (e.g., session_not_found.tpl, follower_loading.html) now correspond to templates within the ss-proxy service.
• To migrate a template, you must first find its new path in the v5 container. For example, to find all customizable templates in the proxy service, you can run podman exec -it ss-proxy ls /app/templates/ on a running v5 instance.

For detailed instructions on the new rebranding mechanism, see the Rebranding guide. After adapting your v4 templates, copy them to a temporary directory. You will move these files to ~/surfly/error_templates/ on the new v5 system.

Update Automation and Monitoring

Review any automation, monitoring, and backup scripts for hard-coded /opt/cobro paths and update them to the new ~/surfly/ directory structure.

Prepare databases

Before you begin the migration, create a full backup of your surfly and console databases using the instructions in Database Backup and Restore.

Step 3: Plan Your Downtime

• Identify whether you will reuse the existing host or provision a new one.
• Allocate time to test configuration changes and smoke tests before declaring success.
• Communicate the expected downtime or failover procedure to stakeholders.

In-place upgrade

Use this path if you cannot provision new infrastructure and want to keep the existing host.

Step 1. Update the host to meet v5 requirements

Upgrade system packages, runtime dependencies, and container tooling to the versions listed under Baseline requirements. Replace Podman 4.x with Podman 5.4.0+ and confirm Systemd 252+ is available. Restart the host if kernel updates were applied.

Step 2. Remove legacy deployment files

After confirming backups are safe, stop all Surfly services and remove the v4.x directories:

System-wide (root) deployments

sudo systemctl stop ss-surfly.target
sudo rm -rf /opt/cobro
sudo rm -f /etc/systemd/system/ss-*.target
sudo rm -f /etc/containers/systemd/ss-*.container
sudo systemctl daemon-reload

Rootless deployments

systemctl --user stop ss-surfly.target
rm -rf /opt/cobro
rm -f ~/.config/systemd/user/ss-*.target
rm -f ~/.config/containers/systemd/ss-*.container
systemctl --user daemon-reload

Confirm that no stray ss-* units remain active before continuing. For more context on unit names and lifecycles, review Services.

Step 3. Install Surfly v5 on the existing host

Work through the System Setup checklist, then follow the deployment guide to install Surfly v5. When prompted, supply the migrated config.env, certificates, templates, and other assets prepared earlier.

Step 4. Validate the upgrade

Once services start, proceed to the Post-Migration Validation section to confirm the upgraded host operates as expected.

Fresh install with data migration

Use this workflow when you can provision a new host or want to minimise risk on the legacy server.

Step 1. Provision and prepare the new host

1. Provision infrastructure that satisfies the system requirements.
2. Follow the System Setup checklist to prepare the OS, create the Surfly service user, and configure container runtimes.
3. Verify that PostgreSQL 16, Redis 6.2.18+, Podman 5.4.0+, and Systemd 252+ are installed and running at the required versions.

Step 2. Install Surfly v5 baseline

Work through the System Setup checklist, then follow the deployment guide to install Surfly v5. When prompted, supply the migrated config.env, certificates, templates, and other assets prepared earlier.

Step 3. Transfer and restore data

1. On the v4.x host, take final backups of the surfly and console databases (see Database Backup and Restore).
2. Copy the dumps to the new host via scp or a secure transfer mechanism. Validate checksums or file sizes to ensure integrity.
3. Restore the databases on the v5 host.
4. Copy the prepared certificates and templates into ~/surfly/certs/ and ~/surfly/error_templates/. Reapply systemd overrides from Rebranding if needed.

Step 4. Cut over traffic

1. Schedule a final sync window to capture recent data changes or sessions, then repeat the backup/restore process if needed using the steps in Database Backup and Restore.
2. Update DNS, load balancer rules, or firewall policies to point users to the new v5 host.
3. Monitor logs, metrics, and user experience for anomalies during the first sessions.
4. Decommission the legacy v4.x environment only after validating functionality, backups, and rollback plans.

Post-Migration Validation

After completing either migration path, perform these checks to ensure your Surfly v5 deployment is fully functional.

• Surfly services are active and reachable (systemctl --user list-dependencies ss-surfly.target).
• ~/surfly/config.env contains all required variables with correct values and permissions.
• Certificates and error templates reside in their new directories and mount correctly (verify via podman exec or by triggering sample errors).
• API calls such as curl localhost:8017/info/ return the expected v5 metadata and license information.
• Database backups are taken on the new environment and stored according to your policy.
• Smoke tests for key workflows (session start, dashboard login, API calls) pass without regressions.

Document any site-specific steps you performed so future upgrades follow the same validated procedure.