← Back to Installation Guide

FoundryVTT Server Management Guide

Essential maintenance tasks for your FoundryVTT server. Focus on these core operations for day-to-day management.

Essential Operations

Accessing Your Server

Connect via Digital Ocean Console

  1. Go to your Digital Ocean dashboard → Droplets
  2. Click on your FoundryVTT droplet
  3. Click the "Access" button
  4. Enter username: fvtt in the console username field
  5. Click "Launch Droplet Console" (see console interface)
  6. You'll be logged in automatically
Alternative: If you prefer SSH: ssh fvtt@foundry.yourdomain.com

Restarting FoundryVTT

When FoundryVTT Prompts You

When FoundryVTT prompts you to restart the server (FoundryVTT restart prompt), or when you experience server issues:

How to Restart

After accessing your server via the console (see above), simply run:

fvtt.py service restart
That's it! Your FoundryVTT server will be back online in about 30-60 seconds.

Repairing Service Configurations

When to Use Repair

If your server is experiencing issues after updates or configuration changes, the repair tool can automatically fix service configurations without requiring a full reinstall.

What it fixes: The repair command checks and repairs both Caddy (web server) and Docker (FoundryVTT container) configurations to match expected settings.

Check What Would Be Fixed (Dry Run)

Before making changes, see what needs repair:

fvtt.py tool repair --dry-run

This will show you:

Safe to run: Dry run mode never makes changes, it only reports what would be done.

Repair All Services

Fix both Caddy and Docker configurations:

fvtt.py tool repair

The repair process will:

  1. Check Caddy configuration: Compare current web server config with expected settings
  2. Update if needed: Apply correct configuration (domain, SSL, ports)
  3. Check Docker configuration: Compare docker-compose.yaml with expected settings
  4. Restart if needed: Stop services, update configuration, restart with correct settings
Downtime: If Docker configuration needs repair, FoundryVTT will be stopped briefly (30-60 seconds) while the configuration is updated.

Repair Individual Services

Fix only specific services:

fvtt.py tool repair caddy

Repairs only the Caddy web server configuration (SSL, domain, routing).

fvtt.py tool repair docker

Repairs only the Docker Compose configuration (container settings, volumes, ports).

When to use individual repair: If you know the issue is with a specific service, you can repair just that service to minimize downtime.

Backup Operations

Understanding Backups

The fvtt.py tool provides two ways to manage backups:

What gets backed up: Backups capture your entire FoundryVTT data directory including worlds, systems, modules, and assets. These are stored as compressed .tar.gz archives.

Using the Backup Server (Recommended)

The backup server provides a secure web interface for managing backups:

fvtt.py backup server

When you start the backup server:

  1. FoundryVTT stops automatically: The service is stopped to ensure data consistency
  2. Secure URL generated: A temporary URL with access key is displayed (e.g., https://yourdomain.com/horde?key=abc123...)
  3. Web interface launches: Access the URL in your browser to manage backups
  4. Auto-expires after 20 minutes: Server shuts down automatically for security
  5. FoundryVTT restarts: When you exit the backup server, FoundryVTT automatically restarts
Active games will be disconnected: When the backup server starts, FoundryVTT stops and all players will be disconnected. Plan accordingly!
Before starting: The tool checks if a world is active and shows player count. You'll be prompted to confirm before stopping the service.

Web Interface Features

In the backup manager web interface you can:

Safety features: Create and restore operations are blocked while FoundryVTT is active to prevent data corruption. Upload and download work anytime.

Command-Line Backup Operations

For scripting or quick operations, use CLI commands:

List Available Backups

fvtt.py backup list

Shows all backups with names, sizes, and dates.

Create New Backup

fvtt.py backup create

Creates a backup with automatic timestamp naming (e.g., Backup_2024-01-15_14-30-45.tar.gz).

fvtt.py backup create mybackup

Creates a backup with custom name (mybackup.tar.gz).

Restore from Backup

fvtt.py backup restore Backup_2024-01-15_14-30-45.tar.gz

Restores FoundryVTT data from the specified backup.

Backup operations require FoundryVTT to be stopped: Use fvtt.py service stop before creating/restoring, then fvtt.py service start after.

View Backup Statistics

fvtt.py backup stats

Shows backup count, total size, disk space available, and FoundryVTT data size.

Remove a Backup

fvtt.py backup remove Backup_2024-01-15_14-30-45.tar.gz

Moves the backup to a pruning directory (safe removal, not permanent deletion).

Backup Best Practices

Two-tier strategy: Use fvtt.py backups for quick restores and Digital Ocean snapshots for disaster recovery.

Connecting with Filezilla

Setting up Filezilla Connection

  1. Download Filezilla: Get it free from https://filezilla-project.org/
  2. Launch Filezilla and open Site Manager from the File menu
  3. Add New Site: Click "New Site" and give it a name like "FoundryVTT Server"
  4. Configure Connection (connection settings):
    • Protocol: SFTP - SSH File Transfer Protocol
    • Host: Your server's domain (foundry.yourdomain.com) or IP address
    • Port: Leave blank (defaults to 22)
    • User: fvtt
    • Logon Type: Key file
    • Key File: Browse and select your SSH private key file (NOT the .pub file) from Digital Ocean setup
  5. Advanced Settings: Click the "Advanced" tab (advanced settings)
    • Default local directory: Choose a folder on your computer (use Browse button)
    • Default remote directory: /opt/foundry/data
  6. Connect: Click "Connect" and accept the prompt about trusting the server's key (trust host key dialog)
Why SSH keys? We use key files instead of passwords because the internet is full of jerks, so we have to use keys to stay secure.

Using Filezilla

Once connected, you'll see your server files (connected server view with file transfer):

Updating FoundryVTT

How to Update the Tool

Start the update process with:

update-fvtt-py

The update tool will:

  1. Check for the latest version from the CDN
  2. Download and verify the update
  3. Install the new version automatically
  4. Preserve your existing configuration
Tool updates: The fvtt.py tool itself can be updated easily without reinstalling your server.

More Concepts

Monthly Maintenance

Run this command once a month to keep your server healthy:

fvtt.py tool cleanup

This automated cleanup command will:

For additional maintenance tasks, also run:

sudo apt update && sudo apt upgrade -y

This will update system security patches and keep your server secure.

Quick Backup Reference

For complete backup documentation, see the Backup Operations section above. Quick commands:

See above: Detailed backup workflows and best practices are covered in the Backup Operations section.

Digital Ocean Automatic Backups

In addition to the built-in backup system, you can enable platform-level backups:

  1. Go to your Digital Ocean dashboard
  2. Click on your FoundryVTT droplet
  3. Go to the "Backups" tab
  4. Click "Enable Backups" (adds $2-3 to your monthly cost)
What you get: Automatic weekly backups of your entire server. If something goes catastrophically wrong, you can restore your whole droplet from any backup point. This is your disaster recovery option.
Two-tier backup strategy: Use fvtt.py backups for quick data restores and Digital Ocean backups for complete disaster recovery.

Server Migration

FoundryVTT automatically stores world backups in data/Backups. To migrate between servers:

  1. Connect to old server using Filezilla
  2. Navigate to backups: Go to data/Backups folder on the server
  3. Download backup files: Drag backup files from server to your computer
  4. Set up new server: Follow the installation guide
  5. Upload to new server: Use Filezilla to upload backup files to data/Backups
  6. Import in FoundryVTT: Use FoundryVTT's world import feature to restore your worlds
About FoundryVTT Backups: These backups are created when you create backups from the FoundryVTT interface and don't require stopping the server.

Basic Troubleshooting

If your FoundryVTT server isn't working, try these steps in order:

  1. Restart first: fvtt.py service restart
  2. Check status: fvtt.py status --debug
  3. View logs: fvtt.py logs --lines 50
  4. Run maintenance: fvtt.py tool cleanup
90% of server issues are solved by simply restarting the service. Always try that first!

Can't access website? DNS can take up to 24 hours to work everywhere. Try http:// instead of https:// temporarily.

Players can't connect? Restart FoundryVTT and make sure the world is running. Have players try incognito/private browsing mode.

Getting More Help

If you're still having trouble:

Remember: Most server issues are temporary and can be fixed with a simple restart or maintenance command.

Complete Command Reference

Status & Monitoring

Service Management

Backup Management

Backup Server: The backup server command launches a temporary web interface for managing backups. It provides a secure URL with an access key that expires after 20 minutes.

Configuration Management

Tool Management

Alternative: You can also update the tool using the system command update-fvtt-py

Getting Help

Focus on the essential operations above. Most problems can be solved with fvtt.py service restart!
Version: