Configuring Puter

Terminology

• root - the "top level" of configuration; if a key-value pair is in/at "the root" that means it is not in a nested object (ex: values under "services" are not at the root).

Config Locations

Running the server will generate a configuration file in one of these locations:

• config/config.json when Using Docker
• volatile/config/config.json in Local Development
• /etc/puter/config.json on a server (or within a Docker container)

Editing Configuration

For a list of all possible config values, see config_values.md

Instead of editing the generated config.json, you can make a config file that references it. This makes it easier to maintain if you frequently update Puter, since you can then just delete config.json to get new defaults.

For example, a local.json might look like this:

{
    // Always include this header
    "$version": "v1.1.0",
    "$requires": [
        "config.json"
    ],
    "config_name": "local",
    
    // Your custom configuration
    "domain": "my-puter.example.com"
}

To use local.json instead of config.json you will need to set the environment variable PUTER_CONFIG_PROFILE=local in the context where you are running Puter.

Sample Configuration

The default configuration generated by Puter will look something like the following (updated 2025-02-26):

{
    "config_name": "generated default config",
    "mod_directories": [
        "{source}/../extensions"
    ],
    "env": "dev",
    "nginx_mode": true,
    "server_id": "localhost",
    "http_port": "auto",
    "domain": "puter.localhost",
    "protocol": "http",
    "contact_email": "hey@example.com",
    "services": {
        "database": {
            "engine": "sqlite",
            "path": "puter-database.sqlite"
        },
        "thumbnails": {
            "engine": "http"
        },
        "file-cache": {
            "disk_limit": 5368709120,
            "disk_max_size": 204800,
            "precache_size": 209715200,
            "path": "./file-cache"
        }
    },
    "cookie_name": "...",
    "jwt_secret": "...",
    "url_signature_secret": "...",
    "private_uid_secret": "...",
    "private_uid_namespace": "...",
    "": null
}

Root-Level Parameters

• domain - origin for Puter. Do not include URL schema (the 'http(s)://' portion)