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.

Clone the Template Repository

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

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)

Log in to your source.flxbl.io instance
Go to Settings > Applications > Generate New Token
Select scopes: read:packages
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:

Update to Latest (update-latest)
- Automatically pulls the newest stable SFP server version
- Recommended for regular maintenance updates
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

Navigate to Your Management Repository
- Go to your sfp-server-management repository on GitHub
- Click on the "Actions" tab
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
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

Planned Updates

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

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

Schema Conflicts: Migration failures occur when manual database changes conflict with expected schema
Data Inconsistency: Direct database modifications may conflict with migration expectations
Version Conflicts: Attempting to apply migrations out of sequence or on modified schemas

Manual Recovery Procedures

If you encounter database issues after a rollback:

Check Server Logs:

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

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

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.

Last updated 4 days ago