GearN Server | Server Settings

Server Settings

GNconfig.debug.json is the local runtime configuration file used when GearN Server starts through the debug workflow. It defines ports, SSL, HTTP, Socket.IO, file uploads, MongoDB, logging, DDoS limits, cluster identity, and bootstrap admin credentials.

Treat this file as environment-specific infrastructure configuration. Development can keep permissive defaults, but production must use locked-down origins, strong secrets, real database URLs, controlled upload limits, and a clear backup strategy.

GNconfig.debug.jsonHTTPSocket.IOMongoDBDDoSCluster

Config File

name identifies the current environment.
options contains all typed runtime setting groups.
Keep one config per environment instead of editing production values by hand.

Configuration Shape

{
    "name": "debug",
    "options": {
        "applicationSettings": {},
        "httpAppSettings": {},
        "socketAppSettings": {},
        "uploadFileSettings": {},
        "databaseSettings": {},
        "otherSettings": {},
        "logSettings": {},
        "ddosSettings": {},
        "clusterSettings": {}
    }
}

Read This First

Never ship the default admin username, password, or private key token.
Never expose MongoDB directly to public traffic.
Keep debug request logging disabled when real player data is present.
Use a reverse proxy, HTTPS, backups, monitoring, and deployment rollback for live servers.

Settings Groups

Group	Controls	Open Details
ApplicationSettings	port, socketPort, useSsl, keyFilePath, certFilePath, ...	View ApplicationSettings
HttpAppSettings	enable, allowOrigin, credentials, allowMethods, allowHeaders, ...	View HttpAppSettings
SocketAppSettings	enable, useEmitter, allowOrigin, credentials, allowMethods, ...	View SocketAppSettings
UploadFileSettings	enable, uploadPath, maxSizeUpload, mimeTypeAccepts	View UploadFileSettings
DatabaseSettings	connectionString, databaseName, logConnectionString, logDatabaseName, options	View DatabaseSettings
OtherSettings	headerIP, idTypeCase, ipApiUrl, cloudScriptExecuteTimeoutInMs	View OtherSettings
LogSettings	logToConsoleEnable, logToFileEnable, logPath	View LogSettings
DdosSettings	socketMaxRequestPerSecondPerIp, socketMaxRequestPerSecondPerPeer, socketMaxPendingRequest, socketMaxRequestSize, httpMaxRequestPerSecondPerIp, ...	View DdosSettings
ClusterSettings	instanceId, isPrimary, privateKeyToken, allNodes	View ClusterSettings

ApplicationSettings

Field	Type	Purpose
port	number	Main HTTP API port. Debug default: 2202.
socketPort	number	Dedicated Socket.IO port. Debug default: 2901.
useSsl	boolean	Enables HTTPS and secure socket transport when key and certificate files are configured.
keyFilePath	string	Path to the SSL private key file. Leave empty when useSsl is false.
certFilePath	string	Path to the SSL certificate file. Leave empty when useSsl is false.
expiredTokenInMs	number	Authentication token lifetime in milliseconds. Debug default: 172800000.
privateKeyToken	string	Secret key used to sign and verify auth tokens. Change this before production.
initRootUsername	string	Username for the first root admin account created during initial database bootstrap.
initRootPassword	string	Password for the first root admin account. Never keep the debug value in production.
restoreRootPassword	string	Emergency fallback password for dashboard admin login and password change flows. Keep it blank unless you intentionally need recovery access.

HttpAppSettings

Field	Type	Purpose
enable	boolean	Enables or disables the HTTP API server.
allowOrigin	string	CORS origin value. Use a strict origin list strategy at the reverse proxy or application boundary for production.
credentials	boolean	Allows credential headers in cross-origin requests.
allowMethods	MethodType[]	HTTP methods accepted by the API. Debug default allows GET and POST.
allowHeaders	string[]	Allowed request headers such as Auth-Token, Secret-Key, Game-Id, and Content-Type.
enableSendAndReceiveDebug	boolean	Logs request and response payloads for debugging. Disable this in production unless you have a controlled incident workflow.
enablePostViaMsgPack	boolean	Enables MessagePack payload handling for HTTP operations.
enablePostViaJson	boolean	Enables JSON payload handling for HTTP operations.
trustProxy	boolean	Tells Express to trust proxy headers. Enable only when GearN is behind a trusted proxy or load balancer.

SocketAppSettings

Field	Type	Purpose
enable	boolean	Enables or disables the Socket.IO server.
useEmitter	boolean	Uses the MongoDB Socket.IO emitter for cross-node socket fan-out.
allowOrigin	string	CORS origin value for socket handshakes.
credentials	boolean	Allows credential headers during socket handshake.
allowMethods	MethodType[]	Allowed HTTP methods for socket handshakes. Debug default is GET.
allowHeaders	string[]	Allowed headers for socket handshake requests.
enableSendAndReceiveDebug	boolean	Logs socket payloads for debugging. Disable in production unless explicitly needed.
enablePostViaMsgPack	boolean	Enables MessagePack payload handling over socket operations.
enablePostViaJson	boolean	Enables JSON payload handling over socket operations.
pingInterval	number	Socket.IO ping interval in milliseconds. Debug default: 50000.
pingTimeout	number	Socket.IO ping timeout in milliseconds. Debug default: 5000.

UploadFileSettings

Field	Type	Purpose
enable	boolean	Enables or disables file upload routes.
uploadPath	string	Local folder where uploaded files are stored. Debug default: ./file-upload.
maxSizeUpload	number	Maximum upload size in bytes. Debug default is 52428800, which is 50 MB.
mimeTypeAccepts	string[]	Accepted MIME types. Debug default accepts image/png only.

DatabaseSettings

Field	Type	Purpose
connectionString	string	MongoDB connection string for main GearN data.
databaseName	string	Main MongoDB database name.
logConnectionString	string \| null	Optional MongoDB connection string for log data. When empty, logs use the main database connection.
logDatabaseName	string	Database name used by the separate log database connection.
options	MongoClientOptions	Extra MongoDB client options such as pool sizes, retry behavior, and timeout values.

OtherSettings

Field	Type	Purpose
headerIP	string	Request header used to resolve the real client IP. Debug default: X-Real-IP.
idTypeCase	0 \| 1 \| 2	Generated ID casing mode. 0 allows mixed case, 1 forces uppercase, and 2 forces lowercase.
ipApiUrl	string	External endpoint used to resolve IP location details. Debug default: https://ipdetail.gearn.net/json.
cloudScriptExecuteTimeoutInMs	number	CloudScript execution timeout in milliseconds. Debug config uses 15000.

LogSettings

Field	Type	Purpose
logToConsoleEnable	boolean	Writes server logs to the console.
logToFileEnable	boolean	Writes server logs to a file.
logPath	string	Path to the server log file. Debug default: ./log/debug/Server.log.

DdosSettings

Field	Type	Purpose
socketMaxRequestPerSecondPerIp	number	Maximum socket requests per second from the same IP.
socketMaxRequestPerSecondPerPeer	number	Maximum socket requests per second from the same socket connection.
socketMaxPendingRequest	number	Maximum pending socket requests before new requests are rejected or throttled.
socketMaxRequestSize	number	Maximum socket request payload size in bytes.
httpMaxRequestPerSecondPerIp	number	Maximum HTTP requests per second from the same IP.
httpMaxRequestPerSecondPerPeer	number	Maximum HTTP requests per second from the same peer.
httpMaxPendingRequest	number	Maximum pending HTTP requests.
httpMaxRequestSize	number	Maximum HTTP request payload size in bytes.
maxUploadPendingRequest	number	Maximum pending upload requests.
maxDownloadPendingRequest	number	Maximum pending download requests.
ipWhiteList	string[]	IP addresses exempt from DDoS throttling. Keep this list small and explicit.

ClusterSettings

Field	Type	Purpose
instanceId	string	Unique identifier for this GearN node.
isPrimary	boolean	Marks whether this node is the primary node for cluster-sensitive workflows.
privateKeyToken	string	Secret token for internal node-to-node trust. Use a different value from debug config.
allNodes	{ instanceId: string; fullUrl: string }[]	List of all GearN nodes with the HTTP URL each node can use to reach the others.

Environment Guidance

dev: local ports, local MongoDB, permissive origins, debug logs allowed.
staging: production-like ports, real auth providers, realistic DDoS limits, separate database.
live: locked secrets, strict origins, controlled upload types, backups, monitoring, and minimal debug output.

Recommended Production Changes

Replace privateKeyDefault, admin, and password.
Set real MongoDB credentials and use a database user with only required privileges.
Disable request payload debug logging unless troubleshooting a controlled issue.
Use strict upload MIME types and sizes based on actual game content requirements.
Review DDoS limits with real traffic patterns before opening the service publicly.

Important: Server settings control runtime behavior, security boundaries, and data access. Do not copy the debug config into production without changing secrets, origins, database credentials, upload policy, logging, and operational limits. If a value behaves unexpectedly, inspect the startup mapping before assuming the JSON file is wrong.