Skip to content

Profiles

The profile block defines an environment‑specific server configuration. Profiles allow the same specification to run differently in development, staging, or production without changing the core application logic.

application "MyApp" version="0.1" {
    // ... entities, queries, views ...

    profile "dev" default=true {
        listen address="127.0.0.1" port=8080
    }

    profile "prod" {
        listen address="0.0.0.0" port=443 cert="server.crt" key="server.key"
    }
}

A profile contains one or more listen nodes, each specifying an address, port, and optional TLS certificates. When Terranova starts, it selects a profile and starts the server accordingly.

Syntax

profile "<name>" [default=true] {
    listen address="<ip>" port=<number> [domain="<domain>"] [cert="<path>"] [key="<path>"]
    // additional listen nodes (optional)
}

Attributes

Attribute Type Required Default Description
name string ✓ – Profile identifier (e.g., "dev", "prod").
default bool false If true, this profile is used when no profile is specified via CLI. At most one profile may have default=true.

Listen Node

Each listen node defines a network endpoint that the server will bind to.

Attribute Type Required Default Description
address string "0.0.0.0" IP address or hostname to bind to.
port int ✓ – TCP port number.
domain string "localhost" Domain name for virtual hosting (used in TLS SNI).
cert string – Path to TLS certificate file (PEM). Required if key is present.
key string – Path to TLS private key file (PEM). Required if cert is present.

If both cert and key are provided, Terranova starts an HTTPS server on that endpoint. Otherwise, it starts an HTTP server.

Important: If the selected profile includes a listen node with a cert and key pair that is invalid (e.g., file not found, malformed PEM, mismatched key, expired certificate), Terranova will not start and will exit with an error.

Profile Selection

Terranova determines which profile to use by the following rules:

  1. CLI flag – If --profile <name> is provided, that profile is used.
  2. Default profile – If exactly one profile has default=true, it is used.
  3. Error – If none of the above applies (multiple profiles, no default, no CLI flag), Terranova exits with an error.

Example CLI usage:

terranova serve --profile prod

Multiple Listen Endpoints

A profile can contain multiple listen nodes. This is useful for listening on both HTTP and HTTPS, or on multiple interfaces.

profile "dual" {
    listen address="127.0.0.1" port=8080          // HTTP for local development
    listen address="0.0.0.0" port=8443 cert="dev.crt" key="dev.key"  // HTTPS on another port
}

Complete Example

application "Blog" version="0.1" {
    entity "User" {
        schema {
            pk "id" type="int"
            field "name" type="string"
        }
    }

    profile "development" default=true {
        listen address="127.0.0.1" port=8080
    }

    profile "staging" {
        listen address="0.0.0.0" port=80
        listen address="0.0.0.0" port=443 cert="staging.crt" key="staging.key"
    }

    profile "production" {
        listen address="0.0.0.0" port=443 cert="prod.crt" key="prod.key"
    }
}

What Terranova Does With Profiles

  • Server startup – Terranova binds to all listen endpoints defined in the selected profile.
  • TLS – When cert and key are provided, the endpoint uses HTTPS.
  • Error on invalid certificates – If any cert/key pair in the selected profile is invalid (missing file, malformed, mismatched, expired, etc.), Terranova refuses to start and reports the error.
  • Multiple profiles – Different profiles can use different ports, addresses, or TLS settings without changing the specification.
  • Default profile – Mark one profile as default=true for convenient local development.

See Also