Deployment Guide

During development you run SmartFoxServer 3 on your own machine and connect via 127.0.0.1. Once your game is working locally, moving to production requires three things:

1. A remote server running SmartFoxServer 3 with the correct ports open
2. Your zone config and Java extension deployed to that server
3. Your Unity build pointing to the server’s public IP address

This guide covers all three steps. The process is identical for all NetCrafter tutorials (Chat, Racing, Character) — the only differences are the zone name and extension name, which come from your schema settings.

You need a machine with a static public IP address that you can SSH into (Linux) or RDP into (Windows). Any VPS (Virtual Private Server) from any provider that gives you full OS access will work.

Operating system

SFS3 runs on any platform that supports Java 21. The recommended choices are:

• Linux — Ubuntu 22.04 LTS (recommended): lowest cost, well-documented, easiest firewall management with UFW.
• Windows Server 2022: familiar if your team works primarily on Windows; SFS3 can be installed as a Windows Service for auto-start.

Minimum specifications (SFS3 Community Edition, 100 users)

Download SmartFoxServer 3 from smartfoxserver.com → Downloads. Choose the package that matches your server OS.

Linux (Ubuntu 22.04)

# 1. Install Java 21 (required by SFS3)
sudo apt update
sudo apt install -y openjdk-21-jdk

# Confirm Java version — should print "openjdk 21..."
java -version

# 2. Download SFS3 for Linux from smartfoxserver.com/downloads
#    Choose the Linux / Mac ZIP package
#    Upload it to your server via SCP or wget from the direct link
#    provided after registration on the SFS3 download page.
#    Example (replace with the actual filename you downloaded):
unzip SFS3_3_x_x.zip
cd SFS3_3_x_x/

# 3. Start SFS3
chmod +x start.sh stop.sh
./start.sh

SFS3 runs in the foreground by default. For a persistent background process, see What’s Next → Auto-restart.

Windows Server

1. Install Java 21 JDK from adoptium.net (Eclipse Temurin recommended)
2. Download the Windows installer from smartfoxserver.com → Downloads
3. Run the installer as Administrator
4. Install to C:\SFS3\ or your preferred location
5. Start via C:\SFS3\start.bat
6. Optionally, register SFS3 as a Windows Service for auto-start after reboot (see SFS3 documentation → Running as a Service)

This is the most common reason remote connections fail. Your server’s firewall must allow incoming connections on the SFS3 port before any client can connect.

Linux (UFW firewall)

sudo ufw allow 9977/tcp
sudo ufw allow 9977/udp
sudo ufw reload
sudo ufw status

Windows Server (Windows Defender Firewall)

1. Open Windows Defender Firewall with Advanced Security
2. Click Inbound Rules → New Rule…
3. Select Port → TCP → enter 9977 → Allow the connection
4. Repeat for UDP 9977

To verify port 9977 is reachable from the outside, use an online port checker (search “open port checker”) and enter your server’s public IP and port 9977 after SFS3 is running.

The zone XML generated by NetCrafter’s Config Generator must be copied to the remote server’s server/zones/ folder.

Generate the zone file

1. In Unity, open the NetCrafter window: Tools → Pivec Labs → NetCrafter Pro
2. Select your schema and go to the Code → Config Generator tab
3. Confirm your SmartFox Settings are correct:
   • Zone Name matches your game (e.g. ChatRoomZone, RacingZone, CharacterZone)
   • Extension Name and Extension Class are set correctly
4. Click Refresh Preview to verify the generated XML
5. Click Generate Config — the file is written to:
   Assets/PivecLabs/NetCrafter/Definitions/{SchemaName}/Generated/Config/{ZoneName}.zone.xml

Copy to the remote server

# Replace placeholders with your actual values
scp {ZoneName}.zone.xml user@YOUR_SERVER_IP:/path/to/sfs3/server/zones/

On Windows, use WinSCP, FileZilla, or any SFTP client to copy the file to /path/to/sfs3/server/zones/ on the remote server.

The filename must end in .zone.xml. SFS3 scans server/zones/*.zone.xml on startup and ignores files that do not match this pattern.

The JAR built by NetCrafter must be copied to a named folder inside the remote server’s server/extensions/ directory.

Build the JAR locally

1. In the NetCrafter window, go to Code → Server Code
2. Confirm SFS3 Lib Path points to your local SFS3 lib/ folder (used for compilation only)
3. Click Build JAR (mvn package) and wait for BUILD SUCCESS
4. The built JAR is at:
   Assets/PivecLabs/NetCrafter/Definitions/{SchemaName}/Generated/Server/target/{SchemaName}Extension.jar

Copy to the remote server

# Create the extension folder on the remote server
# (the folder name must match the Extension Name in your schema settings)
ssh user@YOUR_SERVER_IP \
  "mkdir -p /path/to/sfs3/server/extensions/{ExtensionName}"

# Copy the JAR
scp {SchemaName}Extension.jar \
  user@YOUR_SERVER_IP:/path/to/sfs3/server/extensions/{ExtensionName}/

On Windows, use WinSCP or FileZilla. Copy the JAR to:
C:\SFS3\server\extensions\{ExtensionName}\{SchemaName}Extension.jar

This is the only change needed in your Unity project to connect to a remote server. Change the Host field from the localhost address to your server’s public IP.

1. Open the NetCrafter window: Tools → Pivec Labs → NetCrafter Pro
2. Select your schema
3. Go to Settings → SmartFox Settings
4. Change Host from:

127.0.0.1

To your server’s public IP address:

203.0.113.42  ← example only — use your actual server IP

5. Click Save Settings
6. Click Code → Build Code → Generate All Files to regenerate SmartFoxConnectionManager.cs with the new host embedded
7. Rebuild your Unity client: File → Build

After deploying the zone config and JAR, restart SFS3 on the remote server so it picks up the new files.

Linux

# Stop SFS3
./stop.sh

# Start SFS3
./start.sh

# Stream the log to watch for errors
tail -f logs/smartfox.log

Windows Server

If installed as a Windows Service: open Services, find SmartFoxServer 3, click Restart. Otherwise stop and start start.bat.

Check the log at C:\SFS3\logs\smartfox.log.

What to look for in the log

Loading: zones/{ZoneName}.zone.xml
Zone: {ZoneName}
{ExtensionName}: {ExtensionClass} initialized
SmartFoxServer 3 READY

If you see NullPointerException during zone loading, the zone XML is missing a required element — regenerate the config from NetCrafter and redeploy.

If the extension class is not found, confirm the JAR is in server/extensions/{ExtensionName}/ and that the Extension Class in your schema settings matches the fully-qualified class name in the zone XML.

Run your Unity build and watch both the Unity Console and the remote SFS3 log.

Expected Unity Console output

[SFS3] Connected — waiting for Login()
[SFS3] Login() called with: YourName
[SFS3] OnLogin fired
[SFS3] OnRoomJoin fired

Expected SFS3 server log output

Session created: { IP: YOUR_LOCAL_IP }
User login: { Zone: {ZoneName} }

Troubleshooting

Once your server is running and one client can connect, getting additional players in is straightforward.

1. Share your server’s public IP address with other players
2. Each player updates their SmartFox Settings → Host to the same IP and regenerates client code
3. Each player builds and runs the Unity client
4. All players connect to the same SFS3 zone and room — the server handles routing

Players do not need to know anything about the server setup beyond the IP address and port. The port (9977) is already embedded in the generated SmartFoxConnectionManager.cs via your schema settings.

A production game server is publicly reachable. These steps reduce your attack surface.

Change the Admin Tool default credentials

SFS3 ships with default Admin Tool credentials. Change them immediately after installation:

1. Open the SFS3 Admin Tool at http://YOUR_SERVER_IP:8080/admin
2. Go to Server Settings → Remote Admin
3. Change the username and password to strong, unique values
4. Save and restart SFS3

Restrict Admin Tool access (port 8080)

Do not expose port 8080 to the public internet. Two safe approaches:

• SSH tunnel: access the Admin Tool over an SSH tunnel from your local machine — port 8080 never needs to be open on the firewall
• IP allowlist: in UFW or your hosting provider’s firewall, allow port 8080 only from your own IP address

# Run this on your LOCAL machine
# Then open http://localhost:8080/admin in your browser
ssh -L 8080:localhost:8080 user@YOUR_SERVER_IP

Use SSL / WSS for production

SFS3 supports HTTPS and WebSocket Secure (WSS) connections. For a publicly released game, use WSS to encrypt traffic between clients and the server. See the SFS3 documentation for SSL certificate setup.

Keep SFS3 updated

Check the SmartFoxServer release page periodically and update to the latest stable version to pick up security patches and bug fixes. Test updates on a staging server before applying to production.

Your server is live. Here are the natural next steps for a production-ready deployment: