Skip to content
Archiedocscookbooknewssign in

    Multi-instance deployment

    1. Install the instance

    Choose a name and seven unused consecutive ports. This example uses dev and ports 18000 through 18006.

    The installer shares executables between instances, in ~/.local/bin by default. Installing a different release there replaces the executables used by your existing instance too. Don't use this layout to keep test and production on different archie versions.

    From an archie-core checkout, run:

    bash ./install.sh --instance dev --port-base 18000

    The installer runs setup and creates systemd user services with a -dev suffix. It starts them unless you pass --no-start.

    Use --port-base on the first install. Changing the instance name doesn't change its ports, and the installer won't rewrite addresses in an existing config.toml.

    2. Check the services

    systemctl --user status archied-dev archie-state-store-dev archie-gateway-dev archie-ui-dev archie-messaging-dev

    Check the daemon's readiness on the second port:

    curl -i http://127.0.0.1:18001/health/detailed

    An HTTP 200 means the readiness checks passed. A 503 means the daemon isn't ready; read the response for the failing checks.

    If the daemon won't start, read its logs:

    journalctl --user -u archied-dev -e

    3. Open the dashboard

    On the host, open http://127.0.0.1:18000.

    Each instance uses its own dashboard cookie names, so you can stay signed in to both dashboards in the same browser.

    Change the configuration

    With the default XDG directories, dev uses:

    • ~/.config/dev/config.toml for configuration.
    • ~/.config/dev/env for secrets loaded by its services.
    • ~/.local/share/dev/ for data and the default runtime state.

    If you've set XDG_CONFIG_HOME or XDG_DATA_HOME, those directories sit under the corresponding location instead.

    When running setup yourself, select the instance:

    ARCHIE_INSTANCE=dev archied setup

    The installer sets ARCHIE_INSTANCE=dev in the services. Without it, commands you run directly select the default instance, archie.

    To restart the new daemon:

    systemctl --user restart archied-dev

    The default instance keeps its service names, such as archied. Use the -dev suffix to manage the new instance.

    Instance names must start with a lowercase letter, contain only lowercase letters, digits and hyphens, and be at most 31 characters. The name selects the configuration directory, so it belongs in the environment rather than config.toml.

    Use separate NATS accounts

    Each instance runs its own embedded NATS server by default, so you don't need to configure NATS for this setup.

    If you're using an external NATS server, give each instance a separate server or NATS account. Instance names don't separate task subjects, so instances sharing an account can receive each other's tasks.