# 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**

   ```bash
   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:

   ```bash
   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:

```bash
# 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](https://github.com/flxbl-io/sfp/releases) 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**:

   ```bash
   sfp server logs --tenant my-tenant --tail 100
   ```
2. **Manual Database Restoration** (if needed):

   ```bash
   # 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:

```yaml
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp-server/setting-up/updating-sfp-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.