Updating sfp server

This guide shows you how to set up automated server management and updates for your self-hosted SFP server instance using a ready-to-use management repository. Simply clone the template repository and configure it for your environment.

Prerequisites

Before setting up automated server management, ensure you have:

• ✅ A running SFP server instance (see Installation Guide)

• ✅ GitHub account with repository creation permissions

• ✅ SSH access to your SFP server

• ✅ Access token from source.flxbl.io (your Gitea instance)

• ✅ Basic familiarity with GitHub Actions

Step 1: Clone the SFP Server Management Template

Get the Template Repository

The SFP team provides a ready-to-use server management repository template that includes all necessary GitHub Actions workflows and configurations for updating your SFP server.

1. Clone the Template Repository

   git clone  https://source.flxbl.io/flxbl/sfp-server-mangement-template.git
   cd sfp-server-management-template

2. Create Your Own Management Repository

   • Create a new private repository in your GitHub organization

   • Name it something like sfp-server-management or our-sfp-server-updates

   • Push the cloned template to your new repository:

   git remote set-url origin https://github.com/your-org/sfp-server-management.git
   git push -u origin main

Repository Structure

The management template includes:

sfp-server-management/
├── .github/
│   └── workflows/
│       └── deploy.yml          # Server update workflow
├── README.md                   # Setup and usage instructions
└── .gitignore                  # Git ignore rules

Step 2: Configure Repository Secrets

Navigate to your repository's Settings > Secrets and Variables > Actions, and add the following secrets:

Required Secrets

Secret Name	Description	Example
GITEA_TOKEN	Access token from source.flxbl.io	xxxxxxxxxxxxxxxxxxxx
SSH_PRIVATE_KEY	Private SSH key for server access	-----BEGIN OPENSSH PRIVATE KEY-----...
SSH_HOST	Server hostname or IP address	sfp-server.company.com
SSH_USER	SSH username	ubuntu
TENANT_NAME	Your SFP server tenant name	company-sfp

Optional Secrets

Secret Name	Description	Default
SSH_PORT	SSH port if not standard	22

How to Generate Secrets

Gitea Token (source.flxbl.io)

1. Log in to your source.flxbl.io instance

2. Go to Settings > Applications > Generate New Token

3. Select scopes: read:packages

4. Copy the generated token

SSH Private Key

Since you already have SSH access to your SFP server from the initial setup, use your existing SSH private key:

# Copy your existing private key content for GitHub secret
cat ~/.ssh/id_rsa
# or if you use a different key file
cat ~/.ssh/your-server-key

Note: Use the same private key you used during server installation and management.

Step 3: Understanding the GitHub Actions Workflow

The template repository includes a pre-configured workflow at .github/workflows/deploy.yml with the following key features:

Update Options

The workflow provides two main deployment types:

1. Update to Latest (update-latest)

   • Automatically pulls the newest stable SFP server version

   • Recommended for regular maintenance updates

2. Update to Specific Version (deploy-specific)

   • Deploy a specific version tag (e.g., v48.3.0)

   • Useful for controlled deployments or rollbacks to known versions

Step 4: How to Execute Server Updates

Running Updates from GitHub

1. Navigate to Your Management Repository

   • Go to your sfp-server-management repository on GitHub

   • Click on the "Actions" tab

2. Start a Server Update

   • Click on "SFP Server Update" workflow

   • Click "Run workflow" button

   • Choose your update options:

     • Update to Latest: Automatically updates to the newest stable version

     • Update to Specific Version: Choose a specific version tag (e.g., v48.3.0)

     • CLI Version: Optionally specify SFP CLI version to use

3. Monitor Progress

   • Watch the workflow execution in real-time

   • Review health checks and update status

   • Get detailed deployment summary

   • Receive notifications on success or failure

Step 5: When to Execute Updates

Regular Update Schedule

Recommended Approach:

• Monthly Updates: Check for new stable releases monthly

• Security Updates: Apply security updates within 48 hours

• Major Releases: Plan and test major version upgrades during maintenance windows

Update Triggers

1. Planned Updates

   Trigger: Manual (workflow_dispatch)
   Type: update-latest
   Timing: During maintenance windows

2. Specific Version Deployment

   Trigger: Manual (workflow_dispatch)
   Type: deploy-specific
   Version: Specific version tag (e.g., v48.3.0)

Best Practices

Before Updates

• Check SFP Release Notes for breaking changes

• Notify team members of planned maintenance

• Verify backup retention policy

• Ensure maintenance window availability

During Updates

• Monitor workflow progress in GitHub Actions

• Watch server logs during deployment

• Verify health checks pass

• Test critical functionality

After Updates

• Confirm all services are running

• Test key integrations

• Update internal documentation

• Clean up old backups

Database Migration Considerations

Understanding Migration Limitations

Important: Database migrations are forward-only operations. When you update to a newer version of SFP server, database schema changes are applied that cannot be automatically reversed.

Migration Failure Scenarios

1. Schema Conflicts: Migration failures occur when manual database changes conflict with expected schema

2. Data Inconsistency: Direct database modifications may conflict with migration expectations

3. Version Conflicts: Attempting to apply migrations out of sequence or on modified schemas

Manual Recovery Procedures

If you encounter database issues after a rollback:

1. Check Server Logs:

   sfp server logs --tenant my-tenant --tail 100

2. Manual Database Restoration (if needed):

   # Restore from backup
   psql -h your-db-host -U username -d database_name < backup.sql
   
   # Restart services
   sfp server restart --tenant my-tenant

3. Contact Support: For complex migration issues, contact support with:

   • Server logs

   • Database error messages

   • Version numbers (before/after)

   • Migration failure details

Troubleshooting

Common Issues

Authentication Errors

Error: Authentication failed with source.flxbl.io

Solution: Verify GITEA_TOKEN secret is valid and has read:packages scope.

SSH Connection Issues

Error: Permission denied (publickey)

Solutions:

• Verify SSH private key format in SSH_PRIVATE_KEY secret

• Ensure public key is added to server's authorized_keys

• Check SSH_USER and SSH_HOST values

Version Mismatch

Error: Version 'v1.2.3' not found in registry

Solution: Check available versions in source.flxbl.io registry or use latest.

Database Migration Failures

Error: Database migration failed: column "new_field" already exists

Solutions:

• Check for conflicting manual database changes

• Restore from backup if database is corrupted

• Review migration changes in release notes before updating

Advanced Configuration

Multi-Environment Support

For organizations with multiple SFP server instances:

strategy:
  matrix:
    environment: [staging, production]
    include:
      - environment: staging
        tenant: company-sfp-staging
        host: staging.sfp.company.com
      - environment: production  
        tenant: company-sfp-prod
        host: sfp.company.com

---

Tip: Start with test deployments before using in production. The workflow includes safety features, but testing your specific environment is recommended.