Artifacts

FiveM artifacts are pre-built server binaries distributed by cfx.re. Understanding build types and update procedures is crucial for maintaining a stable server.

Understanding Build Types

FiveM artifacts are categorized into three types based on stability and testing:

Recommended Builds

Purpose: Production-ready, stable builds for live servers.

Characteristics:

Thoroughly tested by the FiveM team
Recommended for all production servers
Updated less frequently (typically weekly or bi-weekly)
Most stable option with minimal breaking changes
Tagged as “recommended” in the artifacts API

When to use:

Live production servers
Servers with active players
When stability is critical

How to identify:

Marked as recommended in the artifacts list
Usually the most recent stable release

Optional Builds

Purpose: Newer builds with additional features, but may have minor issues.

Characteristics:

More recent than recommended builds
Includes latest features and bug fixes
May have minor bugs or edge cases
Generally stable but not as thoroughly tested
Good middle ground between recommended and latest

When to use:

Servers that need latest features
When recommended build has a critical bug fix you need
Development/staging environments
If you’re comfortable with occasional issues

Latest Builds

Purpose: Bleeding-edge builds from the latest commits.

Characteristics:

Built from the most recent code commits
May include experimental features
Highest risk of bugs and breaking changes
Updated multiple times per day
Not recommended for production

When to use:

Testing new features
Development servers only
When you need a specific fix not in optional/recommended
If you’re willing to troubleshoot issues

Warning: Latest builds can break your server or cause data corruption. Always test thoroughly before using in production.

Finding Artifact Versions

Using the Artifacts API

The FiveM artifacts API provides programmatic access to available builds:


# Get recommended build for Linux
curl -s https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/recommended.json | jq -r '.version'
 
# Get optional build for Linux
curl -s https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/optional.json | jq -r '.version'
 
# Get latest build for Linux
curl -s https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/latest.json | jq -r '.version'

Expected Output:


12345-abc123def456

Manual Lookup

Visit the artifacts page:

Linux: https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/
Windows: https://runtime.fivem.net/artifacts/fivem/build_server_windows/master/

Look for files marked as “recommended”, “optional”, or check the latest timestamp.

Downloading Artifacts

Linux (Automated Script)

Create a script to automatically fetch the recommended build:


#!/bin/bash
# save as: /opt/fivem/update-artifacts.sh
 
set -e  # Exit on error
 
ARTIFACTS_DIR="/opt/fivem/artifacts"
BACKUP_DIR="/opt/fivem/backups/artifacts"
BUILD_TYPE="${1:-recommended}"  # Default to recommended
 
# Create directories
mkdir -p "$ARTIFACTS_DIR" "$BACKUP_DIR"
 
# Get version from API
echo "Fetching $BUILD_TYPE build version..."
VERSION=$(curl -s "https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/${BUILD_TYPE}.json" | jq -r '.version')
 
if [ -z "$VERSION" ] || [ "$VERSION" == "null" ]; then
    echo "Error: Failed to fetch version"
    exit 1
fi
 
echo "Found version: $VERSION"
 
# Check if already installed
if [ -f "$ARTIFACTS_DIR/$VERSION/version" ]; then
    echo "Version $VERSION already installed"
    exit 0
fi
 
# Backup current artifacts if they exist
if [ -d "$ARTIFACTS_DIR/current" ]; then
    CURRENT_VERSION=$(cat "$ARTIFACTS_DIR/current/version" 2>/dev/null || echo "unknown")
    BACKUP_PATH="$BACKUP_DIR/$(date +%Y%m%d-%H%M%S)-$CURRENT_VERSION"
    echo "Backing up current version $CURRENT_VERSION to $BACKUP_PATH"
    mkdir -p "$BACKUP_PATH"
    cp -r "$ARTIFACTS_DIR/current"/* "$BACKUP_PATH/" 2>/dev/null || true
fi
 
# Download new artifacts
DOWNLOAD_URL="https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/$VERSION/fx.tar.xz"
DOWNLOAD_PATH="$ARTIFACTS_DIR/fx-$VERSION.tar.xz"
EXTRACT_PATH="$ARTIFACTS_DIR/$VERSION"
 
echo "Downloading from $DOWNLOAD_URL..."
wget -q --show-progress -O "$DOWNLOAD_PATH" "$DOWNLOAD_URL"
 
# Extract
echo "Extracting artifacts..."
mkdir -p "$EXTRACT_PATH"
tar -xf "$DOWNLOAD_PATH" -C "$EXTRACT_PATH" --strip-components=1
 
# Save version
echo "$VERSION" > "$EXTRACT_PATH/version"
 
# Update symlink
echo "Updating current symlink..."
ln -sfn "$EXTRACT_PATH" "$ARTIFACTS_DIR/current"
 
# Cleanup
rm -f "$DOWNLOAD_PATH"
 
echo "Successfully installed version $VERSION"
echo "Artifacts location: $ARTIFACTS_DIR/current"

Usage:


# Make executable
chmod +x /opt/fivem/update-artifacts.sh
 
# Update to recommended (default)
sudo /opt/fivem/update-artifacts.sh
 
# Update to optional
sudo /opt/fivem/update-artifacts.sh optional
 
# Update to latest (not recommended)
sudo /opt/fivem/update-artifacts.sh latest

Linux (Manual Download)


# Set your desired version
VERSION="12345-abc123def456"  # Replace with actual version
 
# Create directory
mkdir -p /opt/fivem/artifacts/$VERSION
cd /opt/fivem/artifacts/$VERSION
 
# Download
wget https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/$VERSION/fx.tar.xz
 
# Extract
tar -xf fx.tar.xz
 
# Cleanup
rm fx.tar.xz
 
# Update symlink (if using)
ln -sfn /opt/fivem/artifacts/$VERSION /opt/fivem/artifacts/current

Windows

Visit https://runtime.fivem.net/artifacts/fivem/build_server_windows/master/
Download the recommended build (marked as such)
Extract the ZIP file to your FiveM server directory
Replace existing files (backup first!)

Safe Update Procedure

Follow this step-by-step process to update artifacts without downtime or data loss:

Step 1: Preparation

Check current version:


# If using the script above
cat /opt/fivem/artifacts/current/version
 
# Or check server startup logs
grep "version" /opt/fivem/logs/server.log | tail -1

Verify backups are working:


# Check backup script/directory exists
ls -la /opt/fivem/backups/

Check disk space:


df -h /opt/fivem
# Ensure at least 2GB free for artifacts download

Step 2: Backup Current State

Backup artifacts:


BACKUP_DIR="/opt/fivem/backups/artifacts/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r /opt/fivem/artifacts/current/* "$BACKUP_DIR/"
echo "Backed up to: $BACKUP_DIR"

Backup server configuration:


# Backup server.cfg and important configs
tar -czf /opt/fivem/backups/config-$(date +%Y%m%d).tar.gz \
    /opt/fivem/server.cfg \
    /opt/fivem/resources/

Database backup (if applicable):


# MariaDB/MySQL
mysqldump -u root -p fivem > /opt/fivem/backups/db-$(date +%Y%m%d).sql

Step 3: Stop Services

Stop FiveM server:


# If using systemd
sudo systemctl stop fivem
 
# Or if using txAdmin
# Stop via txAdmin interface or:
sudo systemctl stop txadmin

Verify services are stopped:


# Check no FXServer process is running
ps aux | grep fxserver
 
# Check ports are free
sudo netstat -tulpn | grep 30120
# Should return nothing

Step 4: Download and Install New Artifacts

Using automated script:


sudo /opt/fivem/update-artifacts.sh recommended

Or manually:


# Follow manual download steps above

Verify installation:


# Check version file exists
cat /opt/fivem/artifacts/current/version
 
# Check executable exists
ls -la /opt/fivem/artifacts/current/FXServer
# Should show executable permissions

Step 5: Test in Staging (Recommended)

If you have a staging environment:

Copy new artifacts to staging server
Start staging server
Test critical functionality:
- Server starts without errors
- Resources load correctly
- Database connections work
- Players can join
Monitor for 15-30 minutes

Step 6: Deploy to Production

Start services:


# Start FiveM server
sudo systemctl start fivem
 
# Or start txAdmin
sudo systemctl start txadmin

Monitor startup:


# Watch logs
sudo journalctl -u fivem -f
# or
tail -f /opt/fivem/logs/server.log

Check for errors:

Look for “ERROR” or “WARNING” messages
Verify resources start correctly
Check database connections

Step 7: Post-Update Verification

Verify server is running:


# Check process
ps aux | grep FXServer
 
# Check port
sudo netstat -tulpn | grep 30120
# Should show FXServer listening
 
# Test connection
nc -zv localhost 30120

Check resource status:

Connect to server via FiveM client
Verify all resources are running
Test critical game functions

Monitor for issues:

Watch server logs for 30-60 minutes
Check player reports
Monitor performance metrics

Rollback Procedure

If the update causes issues, follow these steps to rollback:

Step 1: Stop Server


sudo systemctl stop fivem
# or
sudo systemctl stop txadmin

Step 2: Restore Previous Artifacts

If using automated script backups:


# List available backups
ls -la /opt/fivem/backups/artifacts/
 
# Restore specific backup
BACKUP_VERSION="20241201-120000-12345-abc123"
cp -r /opt/fivem/backups/artifacts/$BACKUP_VERSION/* /opt/fivem/artifacts/current/

Or manually restore:


# If you backed up to a specific location
cp -r /opt/fivem/backups/artifacts/YYYYMMDD-HHMMSS-version/* /opt/fivem/artifacts/current/

Step 3: Restore Configuration (if needed)


# Restore server.cfg if you changed it
tar -xzf /opt/fivem/backups/config-YYYYMMDD.tar.gz -C /

Step 4: Restart Server


sudo systemctl start fivem

Step 5: Verify Rollback

Check server logs for successful startup
Verify version matches previous version
Test server functionality

Best Practices

Update Frequency

Recommended builds: Update monthly or when security patches are released
Optional builds: Update bi-weekly if you need new features
Latest builds: Only for testing, never in production

Pre-Update Checklist

Current version documented
Backups verified and tested
Disk space sufficient (2GB+)
Maintenance window scheduled
Players notified (if applicable)
Staging environment tested (if available)

Post-Update Monitoring

Monitor server logs for 1-2 hours
Check resource performance
Verify database connections
Test critical game functions
Monitor player reports

Version Tracking

Keep a log of artifact versions:


# Create version log
echo "$(date): Updated to $(cat /opt/fivem/artifacts/current/version)" >> /opt/fivem/version-history.log

Troubleshooting

”Version already installed” but server won’t start

Solution:


# Verify symlink is correct
ls -la /opt/fivem/artifacts/current
 
# Check executable permissions
chmod +x /opt/fivem/artifacts/current/FXServer
 
# Verify version file
cat /opt/fivem/artifacts/current/version

Download fails or is corrupted

Solution:


# Retry download
rm -f /opt/fivem/artifacts/fx-*.tar.xz
# Re-run update script or manual download
 
# Verify checksum (if available)
# Some builds provide MD5/SHA256 checksums

Server starts but resources fail

Solution:

Check resource compatibility with new artifact version
Review server logs for specific errors
Some resources may need updates for new artifact versions
Consider rolling back if critical resources fail

Validation

After updating artifacts:

Check version:


cat /opt/fivem/artifacts/current/version
# Should match downloaded version

Verify server starts:


sudo systemctl status fivem
# Should show "active (running)"

Test connection:
- Connect via FiveM client
- Verify server appears in server list
- Join server successfully

Check logs:


tail -n 50 /opt/fivem/logs/server.log
# Should show successful startup, no critical errors