Comprehensive Guide: Migrating from TrueCharts to Docker in TrueNAS SCALE 24.10 Electric Eel

[hhf.technoloy]

Introduction

This comprehensive guide details the migration process from TrueCharts applications to Docker-based deployments in TrueNAS SCALE 24.10 (Electric Eel). This guide is specifically designed for users running TrueNAS SCALE 23.10 (Cobia) or 24.04 (Fangtooth) with TrueCharts applications using PVC storage.

Warning: This guide assumes you’ve been using PVC as your storage configuration. If you’re using host path mounts, some steps may differ, though the general process remains valuable for your migration planning.

Prerequisites

• TrueNAS SCALE 23.10 (Cobia) or 24.04 (Fangtooth)
• Active TrueCharts applications
• Root access to TrueNAS shell
• Sufficient storage space for backups
• All applications should be running during the backup process
• Backup destination path (replace /mnt/tank/mybackup with your preferred location)

Important: Your backup destination dataset should preferably not have ACLs enabled to ensure proper backup of file ownership information.

Pre-Migration Backup Process

1. In-Application Backups

Before proceeding with system-level backups, perform application-specific backups:

1. Check each application for built-in backup/export features
2. Export any databases, configurations, or settings available through application web interfaces
3. Store these backups separately from the system-level backups

2. Configuration Documentation

2.1. UI Configuration Screenshots

1. Install the FireShot browser extension
2. Capture full-page screenshots of each application’s configuration page
3. Pay special attention to:
   • Storage configurations
   • Port mappings
   • Environment variables
   • Custom mount points
   • Persistence settings

Note: These screenshots will prove invaluable when recreating your applications in the new Docker environment.

2.2. Kubernetes Resource Documentation

# Create backup directory
mkdir -p /mnt/tank/mybackup/k3s-info/

# Export detailed deployment configurations
k3s kubectl get pvc -A | sort -u | awk '{print $1}' | tail -n +2 | sort -u | \
  xargs -I {} sh -c 'k3s kubectl -n {} describe deploy > /mnt/tank/mybackup/k3s-info/{}.txt'

# Document PVC mappings
k3s kubectl get pvc -A | sort -u | \
  awk '{print "\t" $1 "\t" $2 "\t" $4}' | column -t | tee /mnt/tank/mybackup/truenas_pvc_names.txt

Your truenas_pvc_names.txt will contain entries like:

NAMESPACE            NAME                                       VOLUME
ix-firefox           firefox-config                            pvc-240f36f9-13f9-4820-a914-660ee7a40f7d
ix-gitea             db-gitea-postgresql-0                     pvc-88bf480b-d305-4d87-b2f5-e19d5b1e8b2f
ix-gitea             gitea-data                               pvc-3258d132-6c3a-4511-872a-8ab16cdbb1ea

Warning: Pay special attention to PVCs prefixed with db- (like db-gitea-postgresql-0). These are typically TrueCharts database volumes that may require special handling:

1. Use application-specific database export features if available
2. Consider taking SQL dumps from within the container
3. Document the database configuration for later restoration

3. PVC Data Backup

3.1. Create Backup Directory Structure

# Create main backup directory
mkdir /mnt/tank/mybackup/apps-pvc-data

# Create application-specific directories (example)
mkdir -p /mnt/tank/mybackup/apps-pvc-data/ix-firefox/firefox-config
mkdir -p /mnt/tank/mybackup/apps-pvc-data/ix-gitea/{db-gitea-postgresql-0,gitea-data}
mkdir -p /mnt/tank/mybackup/apps-pvc-data/ix-jellyfin/{jellyfin-config,jellyfin-transcode}

3.2. Backup PVC Data

Important: Keep all applications running during this process. The backup method relies on active PVC mounts.

For each PVC entry in your truenas_pvc_names.txt:

# Syntax
rsync -ra $(find /var/lib/kubelet/pods/ -name 'PVC-UUID')/mount/ /mnt/tank/mybackup/apps-pvc-data/NAMESPACE/NAME/

# Example for Jellyfin
rsync -ra $(find /var/lib/kubelet/pods/ -name 'pvc-a1e4b06e-adec-4085-8f79-0dc42e8771c3')/mount/ /mnt/tank/mybackup/apps-pvc-data/ix-jellyfin/jellyfin-config/

Verify each backup:

ls -la /mnt/tank/mybackup/apps-pvc-data/ix-jellyfin/jellyfin-config/

4. Complete Kubernetes Pods Backup

Backup the entire pods directory for reference:

tar -acvf /mnt/tank/mybackup/var-lib-kubelet-pods.tar.zst /var/lib/kubelet/pods/

5. Final Verification

Before proceeding:

1. Review all application screenshots
2. Check “Persistence” section for each app
3. Verify all PVC entries are backed up
4. Confirm host path mounts are documented
5. Validate network mount configurations

Pre-Update Cleanup

Warning: This step is crucial before upgrading to Electric Eel to prevent conflicts with iX’s upgrade scripts.

1. Shut down all applications
2. Remove all applications from the UI
3. Unset the application pool
4. Remove the ix-applications dataset:

# Identify dataset location
zfs list | grep ix-applications | head -n 1

# Remove dataset
zfs unmount -f tank/ix-applications
zfs destroy -f tank/ix-applications

Note: If you’re running official TrueNAS apps alongside TrueCharts, consider keeping the dataset and removing only TrueCharts apps.

Post-Update Setup

1. Directory Structure

Create a new apps-data structure:

# Create main dataset
# Use UI: Datasets -> Create -> Name: apps-data -> Preset: Apps

# Create application directories (example for Jellyfin)
mkdir -p /mnt/tank/apps-data/jellyfin/{cache,config}
chown -R 568:568 /mnt/tank/apps-data/jellyfin/{cache,config}

2. Data Restoration

rsync -ra /mnt/tank/mybackup/apps-pvc-data/ix-jellyfin/jellyfin-config/ /mnt/tank/apps-data/jellyfin/config/

Deployment Options

1. Official TrueNAS Applications

Benefits:

• Growing catalog
• Regular updates
• Simplified configuration

Considerations:

• Note user/group IDs:
  • Stable train: 473:473
  • Enterprise/Community: 568:568
• Use host network mode for direct network access
• Avoid iXvolume for persistent data
• Use temporary storage appropriately

2. Docker Compose Custom Apps

Create your compose file:

# /mnt/tank/apps-data/app-name/compose.yml
version: '3'
services:
  your-service:
    image: your-image
    volumes:
      - /mnt/tank/apps-data/app-name/config:/config

Create Custom App:

include:
  - /mnt/tank/apps-data/app-name/compose.yml

Note: In RC1, editing compose files requires app recreation. This is fixed in the stable release.

Docker Management

Useful commands:

# List projects
docker compose ls

# Manage specific app
docker compose -p ix-app-name ps

Warning: Don’t run docker compose directly in your compose.yml directory - use the project name (-p) flag instead.

Troubleshooting

Common Issues

1. Permission Problems

   • Verify UID/GID mappings
   • Check filesystem permissions
   • Consider user/group ownership requirements

2. Mount Point Issues

   • Verify path existence
   • Check mount point permissions
   • Confirm container user access rights

3. Database Restoration

   • Follow application-specific restore procedures
   • Verify database user permissions
   • Check connection configurations

Best Practices

1. Maintain regular configuration backups
2. Document all custom modifications
3. Use host paths for large data stores
4. Keep application configs in a centralized location
5. Regular testing of backup restoration
6. Maintain proper permissions management

Limitations and Considerations

1. Custom App limitations:

   • No relative path support
   • Environment file challenges
   • Limited Dockerfile integration
   • Configuration backup complexities

2. Permission considerations:

   • Different UID/GID requirements
   • Application-specific ownership needs
   • Filesystem permission inheritance

Conclusion

This migration process, while complex, ensures a clean transition to Docker-based deployments in TrueNAS SCALE 24.10. Following these steps systematically will help maintain data integrity and application functionality throughout the migration process.

Remember to:

• Backup thoroughly before starting
• Document all configurations
• Test restores when possible
• Maintain proper permissions
• Follow application-specific guidelines