GNconfig.debug.json – The Configuration Heart of GearN Server
Within every GearN Server project, you’ll find a vital file named GNconfig.debug.json. This isn’t just another config file — it serves as the blueprint and control center that tells GearN Server exactly how to operate in your local or debug environment.
Think of it as the brain of your backend during development. It defines all critical technical parameters — from network ports and security protocols, to HTTP and WebSocket APIs, DDoS protection, database access, file uploads, and even cluster topology for distributed nodes.
Through GNconfig.json, GearN Server will understand:
- Which ports to listen on (port, socketPort)
- Whether SSL should be enabled or disabled
- What origins and headers are allowed for CORS
- How to protect itself against abuse or DDoS attacks
- Which MongoDB connection to use for storing player data
- Which nodes belong to your cluster and which one is the primary
Because it’s written in clean, structured JSON, you can easily:
- Modify it for different environments (development, staging, production)
- Integrate it with CI/CD pipelines for dynamic config loading
- Clearly document and organize nested configurations
In short, GNconfig.json is the key that allows GearN Server to understand how you want it to run — enabling a backend that is precise, secure, and adaptable to your game’s needs.
{
"name": string,
"options": {
"applicationSettings": ApplicationSettings,
"httpAppSettings": HttpAppSettings,
"socketAppSettings": SocketAppSettings,
"uploadFileSettings": UploadFileSettings,
"databaseSettings": DatabaseSettings,
"otherSettings": OtherSettings,
"logSettings": LogSettings,
"ddosSettings": DdosSettings,
"clusterSettings": ClusterSettings
}
}
ApplicationSettings
port number: Main HTTP port the http server listens on (default: 2202).
socketPort number: Port dedicated to Socket.IO (default: 2901).
useSsl boolean: Whether to enable SSL (HTTPS, WSS) (default: false).
keyFilePath / certFilePath string: Paths to SSL key and certificate files (if useSsl = true).
privateKeyToken string: The private key used for signing/verifying Auth Tokens, let change to another privateKeyToken random.
HttpAppSettings
enable boolean: Enables or disables the Http API.
allowOrigin string | string[]: Allowed CORS origins (* = all).
credentials boolean: Allow sending credentials (cookies/auth headers).
allowMethods ("POST", "GET")[]: Allowed HTTP methods (GET, POST, etc.).
allowHeaders string[]: Allowed HTTP headers in requests.
enableSendAndReceiveDebug boolean: Enable HTTP request/response logging on log4js (debug mode).
enablePostViaMsgPack boolean: Allow sending MsgPack payloads via HTTP.
enablePostViaJson boolean: Allow sending JSON payloads via HTTP.
SocketAppSettings
enable boolean: Enables or disables the Socket API.
useEmitter boolean: Whether to use MongoDb emitter for socket cluster communication.
allowOrigin string | string[]: Allowed CORS origin for socket connections (* = all).
credentials boolean: Enable credential headers in socket handshake.
allowMethods ("GET")[]: Allowed HTTP methods for socket connections (usually only GET).
allowHeaders string[]: Allowed socket handshake headers.
enableSendAndReceiveDebug boolean: Enable socket data debug logging.
enablePostViaMsgPack boolean: Support MsgPack communication via socket.
enablePostViaJson boolean: Support JSON communication via socket.
pingInterval number: Interval (ms) between ping messages to clients.
pingTimeout number: Time (ms) to wait for a pong response before disconnecting.
UploadFileSettings
enable boolean: Enables file uploads.
uploadPath string: Local directory to store uploaded files.
maxSizeUpload boolean: Maximum allowed file size (in bytes).
mimeTypeAccepts string[]: Accepted MIME types (e.g., only image/png).
DatabaseSettings
connectionString string: MongoDB connection string for main game data.
logConnectionString string: Optional separate MongoDB for logs (can be null), if set it, any logs will store at here.
databaseName string: Name of the main database.
options : Additional MongoDB client options (leave empty by default).
OtherSettings
headerIP string: Header used to get the real client IP (when behind proxy).
idTypeCase 0 | 1 | 2: Type of ID formatting (e.g., 0: random with lowercase and uppercase, 1: just uppercase, 2: just lowercase).
ipApiUrl string: External API to fetch IP-based location details. suggestion use https://ipdetail.gearn.net/json
LogSettings
logToConsoleEnable boolean: Enable logging to terminal/console.
logToFileEnable boolean: Enable writing logs to a file.
ipApiUrl string: Path to the server.log file.
DdosSettings
socketMaxRequestPerSecondPerIp number: Max socket requests per second per IP.
socketMaxRequestPerSecondPerPeer number: Max socket requests per second per connection.
socketMaxPendingRequest number: Max number of pending socket requests in queue.
socketMaxRequestSize number: Max size per socket request (in bytes).
httpMaxRequestPerSecondPerIp number: Max HTTP requests per second per IP.
httpMaxRequestPerSecondPerPeer number: Max HTTP requests per second per client.
httpMaxPendingRequest number: Max pending HTTP requests.
httpMaxRequestSize number: Max size per http request (in bytes).
maxUploadPendingRequest / maxDownloadPendingRequest number: Upload/download throttling limits.
ipWhiteList string[]: List of IPs exempt from DDoS protection (e.g., "your public ip", "127.0.0.1", ...).
ClusterSettings
instanceId string: Unique identifier for this node.
isPrimary boolean: Whether this node is the primary node in the cluster.
privateKeyToken string: Token used to authenticate internal communication between nodes.
allNodes { "instanceId": string, "fullUrl": string }[]: List of all nodes in the cluster (used for internal routing, health checks, etc.). instanceId is name of other instance, fullUrl is http address to other instance.