doc/self-hosters/config.md

# 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](#using-docker)
- `volatile/config/config.json` in [Local Development](#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](./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:

```json
{
    // 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):

```json
{
    "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)
-