Prerequisites

• Docker and Docker Compose installed
  • Quick install (Linux): curl -fsSL https://get.docker.com | sh
  • Or follow official guide: Get Docker
• A Steam account with Stardew Valley purchased
• 2GB RAM minimum, 4GB recommended
• 2GB free disk space

Step 1: Download Configuration Files

# Clone the repository
git clone https://github.com/AmigaMeow/puppy-stardew-server.git
cd puppy-stardew-server

# Or download files directly
mkdir puppy-stardew && cd puppy-stardew
wget https://raw.githubusercontent.com/AmigaMeow/puppy-stardew-server/main/docker-compose.yml
wget https://raw.githubusercontent.com/AmigaMeow/puppy-stardew-server/main/.env.example

Step 2: Configure Environment

# Copy environment template
cp .env.example .env

# Edit with your Steam credentials
nano .env  # or use your favorite editor

.env example:

STEAM_USERNAME=your_steam_username
STEAM_PASSWORD=your_steam_password
ENABLE_VNC=true
# Leave blank to auto-generate a random password at startup
# (retrieve with: docker exec <container> cat /home/steam/web-panel/data/vnc_password.txt)
VNC_PASSWORD=

Important: You MUST own Stardew Valley on Steam. Game files are downloaded via your account.

Step 3: Initialize Data Directories

CRITICAL: This step prevents "Disk write failure" errors!

# Run the initialization script (Recommended)
./init.sh

# Or manual setup
mkdir -p data/{saves,game,steam,logs,backups,custom-mods}
chown -R 1000:1000 data/

Step 4: Start the Server

# Start the server
docker compose up -d

# View logs
docker logs -f puppy-stardew

If Steam Guard is enabled, you'll need to enter the code:

docker attach puppy-stardew
# Paste your Steam Guard code and press ENTER
# IMPORTANT: No output will be shown - this is normal!
# Wait a few seconds, game download will start automatically
# Press Ctrl+P Ctrl+Q to detach (NOT Ctrl+C!)

# Real-time logs
docker logs -f puppy-stardew

# Last 100 lines
docker logs --tail 100 puppy-stardew

docker compose restart

docker compose down

docker compose down
docker pull truemanlive/puppy-stardew-server:latest
docker compose up -d

# Manual backup
tar -czf backup-$(date +%Y%m%d).tar.gz data/saves/

# Or use the backup script (after running quick-start.sh)
./backup.sh

You can replace the current save or upload a new one at any time.

Method 1: Upload Save from Your PC

1. Locate your save on your PC:

   • Windows: %AppData%\StardewValley\Saves\YourFarm_123456789\
   • Mac: ~/.config/StardewValley/Saves/YourFarm_123456789/
   • Linux: ~/.config/StardewValley/Saves/YourFarm_123456789/

2. Upload to server:

   # Copy the entire save folder to the server
   scp -r YourFarm_123456789/ root@your-server:/root/puppy-stardew-server/data/saves/Saves/

3. Restart container (it will auto-fix permissions):

   docker compose restart

4. Verify:

   docker logs -f puppy-stardew
   # Look for: "✓ SAVE LOADED SUCCESSFULLY"

Method 2: Replace Existing Save

1. Backup current save (optional but recommended):

   tar -czf old-save-$(date +%Y%m%d).tar.gz data/saves/

2. Remove old save:

   rm -rf data/saves/Saves/OldFarm_*

3. Upload new save (same as Method 1, step 2-4)

Important Notes

• Permissions are auto-fixed: The container automatically fixes file permissions on startup (v1.0.59+)
• No manual chown needed: Just restart the container after uploading
• Save format: Must be a co-op save (created via CO-OP menu, not "New" menu)
• ServerAutoLoad: Will automatically detect and load the new save

Troubleshooting

If save doesn't load:

# Check if save files exist
docker exec puppy-stardew ls -la /home/steam/.config/StardewValley/Saves/

# Check permissions (should be steam:steam or 1000:1000)
docker exec puppy-stardew ls -l /home/steam/.config/StardewValley/Saves/YourFarm_*/

# Force restart to trigger permission fix
docker compose restart

Cause: Data directories have wrong permissions.

Fix (v1.0.59+):

# Simply restart the container - it will auto-fix permissions
docker compose restart

Manual fix (if auto-fix doesn't work):

chown -R 1000:1000 data/
docker compose restart

Note: Since v1.0.59, the container automatically fixes file permissions on startup. You only need to restart the container after uploading files.

If you have Steam Guard enabled:

docker attach puppy-stardew
# Paste the code from your email/mobile app and press ENTER
# IMPORTANT: You won't see any output - this is normal!
# Wait a few seconds for game download to start automatically
# Press Ctrl+P Ctrl+Q to detach (NOT Ctrl+C!)

Tip: Consider using Steam Guard mobile app for faster codes.

1. Check logs: docker logs puppy-stardew
2. Verify Steam credentials in .env
3. Ensure you own Stardew Valley on Steam
4. Check disk space: df -h
5. Restart: docker compose restart

1. Check firewall: Port 24642/udp must be open

   # Ubuntu/Debian
   sudo ufw allow 24642/udp
   
   # CentOS/RHEL
   sudo firewall-cmd --add-port=24642/udp --permanent
   sudo firewall-cmd --reload

2. Verify server is running:

   docker ps | grep puppy-stardew

3. Check if save is loaded: Connect via VNC or check logs for "Save loaded"

4. Ensure game versions match: Server and clients must have same Stardew Valley version

Fixed in v1.0.58!

If you still experience this after updating:

1. Pull latest image:

   docker compose down
   docker pull truemanlive/puppy-stardew-server:latest
   docker compose up -d

2. Check mod version:

   docker logs puppy-stardew | grep "Skill Level Guard"
   # Should show v1.4.0

3. Verify auto-enable logs:

   docker logs puppy-stardew | grep "Auto mode on"
   # Should show "Auto mode on!" message

The server automatically restarts the game if it crashes. Restarts are rate-limited to prevent infinite loops.

Configuration (via environment variables in .env):

ENABLE_CRASH_RESTART=true        # Enable/disable auto-restart (default: true)
CRASH_RESTART_DELAY=10           # Seconds to wait before restarting (default: 10)
CRASH_RESTART_MAX=5              # Max restarts within the cooldown window (default: 5)
CRASH_RESTART_COOLDOWN=3600      # Cooldown window in seconds (default: 3600 = 1 hour)

How it works:

• If the game process exits unexpectedly, the entrypoint script detects it and restarts
• A maximum of CRASH_RESTART_MAX restarts are allowed within CRASH_RESTART_COOLDOWN seconds
• If the limit is exceeded, the container stops to prevent restart loops
• Check logs for restart events: docker logs puppy-stardew | grep "restart"

Monitor your server health with Prometheus-compatible metrics at http://your-server:9090/metrics.

Enable metrics (in .env):

ENABLE_METRICS=true
METRICS_PORT=9090

Expose the port (in docker-compose.yml):

ports:
  - "24642:24642/udp"
  - "5900:5900/tcp"
  - "9090:9090/tcp"   # Prometheus metrics

Available metrics:

• stardew_players_online - Number of connected players
• stardew_server_uptime_seconds - Server uptime
• stardew_crash_restarts_total - Total crash restarts
• stardew_save_last_loaded_timestamp - Last save load time

Example Prometheus scrape config:

scrape_configs:
  - job_name: 'stardew'
    static_configs:
      - targets: ['your-server:9090']

Choose which save file to auto-load by setting the SAVE_NAME environment variable.

Configuration (in .env):

SAVE_NAME=MyFarm_123456789

How it works:

• If SAVE_NAME is set, ServerAutoLoad will load that specific save
• If not set, the most recently modified save is loaded (default behavior)
• The save name must match the folder name in data/saves/Saves/

List available saves:

ls data/saves/Saves/
# Output: MyFarm_123456789  AnotherFarm_987654321

Install your own SMAPI mods by placing them in the data/custom-mods/ directory.

Step 1: Create the custom mods directory (if not already present):

mkdir -p data/custom-mods

Step 2: Download and extract your mod into the directory:

# Example: Install a mod from Nexus Mods
unzip CJBCheatsMenu-1.35.0.zip -d data/custom-mods/

Step 3: Restart the server:

docker compose restart

How it works:

• On startup, the container copies mods from data/custom-mods/ into the SMAPI Mods folder
• Mods persist across container recreations via the volume mount
• Each mod should be in its own subfolder with a manifest.json

Directory structure:

data/custom-mods/
├── CJBCheatsMenu/
│   ├── manifest.json
│   └── CJBCheatsMenu.dll
└── ChatCommands/
    ├── manifest.json
    └── ChatCommands.dll

Restrict who can join your server using a whitelist or blacklist.

Configuration (in .env):

PLAYER_ACCESS_MODE=whitelist      # "whitelist", "blacklist", or "open" (default: open)
PLAYER_ACCESS_FILE=data/player-access.json

Whitelist example (data/player-access.json):

{
  "mode": "whitelist",
  "players": [
    { "name": "FarmerJane", "note": "My friend" },
    { "name": "FarmerBob", "note": "Brother" }
  ]
}

Blacklist example (data/player-access.json):

{
  "mode": "blacklist",
  "players": [
    { "name": "Griefer123", "note": "Destroyed crops" }
  ]
}

How it works:

• whitelist mode: Only listed players can join
• blacklist mode: Listed players are blocked from joining
• open mode: Anyone can join (default)
• Changes take effect on server restart

Use Docker Secrets for secure credential storage instead of plain-text .env files.

Step 1: Create secret files:

echo "your_steam_username" | docker secret create steam_username -
echo "your_steam_password" | docker secret create steam_password -
echo "your_vnc_password" | docker secret create vnc_password -

Step 2: Update docker-compose.yml:

services:
  stardew:
    image: truemanlive/puppy-stardew-server:latest
    secrets:
      - steam_username
      - steam_password
      - vnc_password
    environment:
      - STEAM_USERNAME_FILE=/run/secrets/steam_username
      - STEAM_PASSWORD_FILE=/run/secrets/steam_password
      - VNC_PASSWORD_FILE=/run/secrets/vnc_password

secrets:
  steam_username:
    external: true
  steam_password:
    external: true
  vnc_password:
    external: true

How it works:

• Secrets are mounted as files at /run/secrets/<name> inside the container
• The entrypoint script reads *_FILE environment variables and loads values from those files
• Secrets are never exposed in docker inspect or process listings
• Note: Docker Secrets require Docker Swarm mode (docker swarm init)

Alternative for Docker Compose (non-Swarm):

secrets:
  steam_username:
    file: ./secrets/steam_username.txt
  steam_password:
    file: ./secrets/steam_password.txt

Mod configs are in /home/steam/stardewvalley/Mods/ inside the container:

# Edit AutoHideHost config
docker exec puppy-stardew nano /home/steam/stardewvalley/Mods/AutoHideHost/config.json

# Edit Always On Server config
docker exec puppy-stardew nano /home/steam/stardewvalley/Mods/AlwaysOnServer/config.json

# Edit ServerAutoLoad config
docker exec puppy-stardew nano /home/steam/stardewvalley/Mods/ServerAutoLoad/config.json

After editing, restart the server:

docker compose restart

Edit docker-compose.yml:

ports:
  - "24642:24642/udp"  # Change first number to your desired port
  - "5900:5900/tcp"    # VNC port

Restart after changes:

docker compose up -d

Edit .env:

ENABLE_VNC=false

Restart:

docker compose up -d

This saves ~50MB RAM.