Skip to Content
FontegoDocs

Server, settings and config

fontego-server's commands, the settings an admin can change, and every key of the config file.

fontego-server

The server's own program: it runs the server and sets it up on the machine where it runs. Every command works without questions, so a script or an agent can install Fontego from start to finish. In the container it is docker compose exec server fontego-server ....

fontego-server 0.1.0

Usage: fontego-server <command> [options]

  serve                                   Run the server (FONTEGO_HOST, FONTEGO_PORT, FONTEGO_DATA_DIR, FONTEGO_CONFIG)
  init EMAIL [options]                    First run, without questions: the server admin and a link to set their
                                          password, the visible name and the first workspace. Each option can go in
                                          [init] of the config file instead; running it again changes nothing that is there
      --admin-name NAME                   The admin's name
      --display-name NAME                 The name the web app shows (an admin can change it later)
      --token                             Also a token for the CLI, shown once
      --workspace SLUG                    The first workspace, with the admin as its admin, filled from one of:
        (nothing)                           empty
        --template NAME                     a template (fontego-server templates)
        --from PATH                         a folder or a .zip on this machine
        --git URL|PATH [--branch B]         a Git repository, with its history (--no-history: only its last version)
      --workspace-name NAME, --workspace-description TEXT, --workspace-category C
  admin-link EMAIL                        A link to set someone's password, for when nobody can sign in or there is
                                          no mail (it resets the password of an account that has one)
  user add EMAIL [--name NAME] [--admin]  Create an account without a password (to invite people: fontego admin users invite)
  user list
  token create EMAIL [--label L] [--agent]  Print a new token for that person (or for their agent)
  token list EMAIL
  token revoke ID
  workspace create SLUG [--name N] [--description D] [--category C] [--owner EMAIL]
                   [--template NAME | --from PATH | --git URL|PATH [--branch B] [--no-history]]
                                          The owner (default: the first server admin) becomes its admin
  workspace list
  templates                               The templates a workspace can start from
  member set SLUG EMAIL ROLE              ROLE: reader | editor | admin
  member remove SLUG EMAIL
  doctor [--mail-to EMAIL] [--strict]     What works and what production still needs: git, the data folder and its
                                          permissions, the admin, the public URL and its HTTPS, mail, backups.
                                          Exits 1 if something fails (--strict: or needs attention)

Add --json to get machine-readable output.

Settings

What a server admin can change while the server runs, from the web or with fontego admin settings set. Each value comes from the first place that has it: the server's config (the variable, or the key in the config file), which pins it; what an admin set; or the default.

SettingTypeDefaultPinned by
displayNamestringFontegoFONTEGO_DISPLAY_NAME, or displayNameName people see in the web app and in mail.
smtp.hoststringnoneFONTEGO_SMTP_HOST, or host in [smtp]SMTP server. Without one, mail waits for an admin to pass it on.
smtp.portnumber587FONTEGO_SMTP_PORT, or port in [smtp]SMTP port.
smtp.securebooleannoneFONTEGO_SMTP_SECURE, or secure in [smtp]TLS from the start; otherwise STARTTLS when the server offers it. Unset: on for port 465.
smtp.userstringnoneFONTEGO_SMTP_USER, or user in [smtp]SMTP user, if the server asks for one.
smtp.passwordstringnoneFONTEGO_SMTP_PASSWORD, or password in [smtp]SMTP password. It can be set, never read back. FONTEGO_SMTP_PASSWORD_FILE keeps it out of the database.
smtp.fromstringnoneFONTEGO_SMTP_FROM, or from in [smtp]Sender of every message: an address, or "Name <address>".
sessions.web.idleDaysnumber30FONTEGO_SESSIONS_WEB_IDLE_DAYS, or idleDays in [sessions.web]Browser sessions: days unused before they end (applies at once to open sessions).
sessions.web.maxDaysnumber90FONTEGO_SESSIONS_WEB_MAX_DAYS, or maxDays in [sessions.web]Browser sessions: days at most from when they open (lowering it shortens open sessions too).
sessions.cli.idleDaysnumber30FONTEGO_SESSIONS_CLI_IDLE_DAYS, or idleDays in [sessions.cli]CLI sessions: days unused before they end (applies at once to open sessions).
sessions.cli.maxDaysnumber90FONTEGO_SESSIONS_CLI_MAX_DAYS, or maxDays in [sessions.cli]CLI sessions: days at most from when they open (lowering it shortens open sessions too).
paths.protectedlist**/AGENTS.md, **/CLAUDE.md, **/.agents/**, **/.claude/**, **/.github/copilot-instructions.md, **/.github/instructions/**, **/.opencode/**, **/.cursor/rules/**FONTEGO_PATHS_PROTECTED, or protected in [paths]Paths only a workspace's admins can change, for workspaces without their own list (fontego workspace paths).
paths.rejectedlist**/.claude/settings*.json, **/.mcp.json, **/.vscode/mcp.json, **/.cursor/mcp.json, **/opencode.json, **/opencode.jsonc, **/.opencode/plugin/**, **/.opencode/plugins/**FONTEGO_PATHS_REJECTED, or rejected in [paths]Paths nobody can write, because those files would run code on the machines of everyone who syncs, for workspaces without their own list.

The config file

Every key, commented. Point FONTEGO_CONFIG at the file; a FONTEGO_* variable wins over the same key here. How the layers fit together is in Configuration.

# A config file for fontego-server: point FONTEGO_CONFIG at it. Everything is optional, and a FONTEGO_* variable
# wins over the same key here. One file can describe a whole install: how the server runs (the top, read at every
# start) and what `fontego-server init` sets up the first time ([init], read only by init).

# --- How the server runs (a restart applies a change) ---

host = "127.0.0.1"                         # FONTEGO_HOST; 0.0.0.0 in the container
port = 8740                                # FONTEGO_PORT
dataDir = "/var/lib/fontego"               # FONTEGO_DATA_DIR: every workspace and the database; only the server's user may enter it
publicUrl = "https://fontego.example.org"  # FONTEGO_PUBLIC_URL: the address people and their CLIs use, behind a proxy with HTTPS
# templatesDir = "/etc/fontego/templates"  # FONTEGO_TEMPLATES_DIR: this instance's own templates, one folder each
# clientIpHeader = "cf-connecting-ip"      # FONTEGO_CLIENT_IP_HEADER: the header the proxy in front puts the caller's
                                           #   address in (x-real-ip for nginx). Set it behind a proxy, or every caller
                                           #   shares the proxy's address and its limits; only if all traffic comes through it

[storage]
type = "disk"                              # FONTEGO_STORAGE; "s3" will come, with its bucket and endpoint here

[identity]
type = "local"                             # FONTEGO_IDENTITY: accounts with a password; "oidc" will come

[policy]
maxFileBytes = 20971520                    # FONTEGO_MAX_FILE_BYTES
blockSecrets = true                        # FONTEGO_BLOCK_SECRETS

# [import]
# privateNetworks = false                  # FONTEGO_IMPORT_PRIVATE_NETWORKS: let a Git import through the API reach
                                           #   private addresses (this machine, its networks, a VPN). Off: public only

# Backups are the deployment's business. Have the backup job touch this file when it succeeds, and
# fontego-server doctor says how old the last one is.
# [backups]
# stamp = "/var/lib/fontego-backup/last-success"   # FONTEGO_BACKUP_STAMP
# maxAgeHours = 36                                 # FONTEGO_BACKUP_MAX_AGE_HOURS

# --- Settings an admin could change while it runs: set here, they are pinned and win ---

# displayName = "Fontego"                  # FONTEGO_DISPLAY_NAME; to only start with a name, use [init] instead
# [smtp]
# host = "smtp.example.org"                # FONTEGO_SMTP_HOST, _PORT, _SECURE, _USER, _FROM
# port = 587
# user = "fontego@example.org"
# passwordFile = "/run/secrets/smtp_password"   # FONTEGO_SMTP_PASSWORD_FILE
# from = "Fontego <fontego@example.org>"
# [sessions.web]
# idleDays = 30
# maxDays = 90

# --- The first run: fontego-server init (options on its command line win) ---

[init]
admin = "you@example.org"                  # init EMAIL: the server admin, who gets a link to choose a password
# adminName = "Your Name"                  # --admin-name
# displayName = "Our team"                 # --display-name: the name to start with; an admin can change it later
# token = true                             # --token: also a token for the CLI, shown once

[init.workspace]                           # --workspace SLUG: the first workspace, with the admin as its admin
slug = "notes"
# name = "Notes"
template = "demo"                          # --template NAME, or one of:
# from = "/srv/import/notes"               #   --from: a folder or a .zip on this machine
# git = "https://example.org/notes.git"    #   --git: a Git URL or a repository on this machine, with its history
# branch = "main"                          #   --branch
# history = false                          #   --no-history: only its last version

On this page