APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

Application Bootstrap

The fourth bootstrap step loads installed application configurations, validates their contexts and routes, and resolves the application and context for the current HTTP request or process execution.

Purpose and Execution

Bootstrap\Application\ApplicationBootstrap executes after Runtime Bootstrap and before CORS Bootstrap. It operates on the existing RuntimeState instance.

public function boot(): void
{
    $applications = $this->validateApplications($this->loadApplications());

    $this->runtimeState->setApplications($applications);
    $this->runtimeState->setApplicationSlugs(
        $this->collectApplicationSlugs($applications),
    );

    if ($this->isCoreCommandRuntime()) {
        $this->applyCoreProcessContext();
        return;
    }

    if ($this->runtimeState->getProcess()) {
        $this->resolveProcessApplication($applications);
        return;
    }

    $this->resolveRuntimeApplication($applications);
}

Application discovery and validation happen before the runtime branches into core commands, application processes, or HTTP routing. This step does not load application PHP classes or copy installation templates.

Complete Application Configuration

Installed application configurations reside in platform/application/. The following example is based on the appnetos-docs application:

<?php

declare(strict_types=1);

return [
    'application' => 'appnetos-docs',
    'active' => true,
    'contexts' => [
        'app',
    ],
    'default_context' => 'app',
    'base_contexts' => [
        'app' => 'app',
    ],
    'routes' => [
        'app' => [
            'slug' => 'docs',
            'hosts' => [],
        ],
    ],
];
Key Type Required Purpose
application string Yes Application identifier; matches the configuration filename.
active bool No Enables runtime resolution; defaults to true.
contexts array Yes Declares available application contexts.
default_context string Yes Declares a default context that belongs to contexts.
base_contexts array Yes Maps each context to the APPNETOS app or admin base.
routes array Yes HTTP routes for all non-process contexts.
routes.<context>.slug string Conditional First URI segment; an empty string defines a root route.
routes.<context>.hosts array No Optional explicit host scope; normalized during validation.

A route requires a string slug or a non-empty hosts array. A host-only route may omit slug.

Application Identity and Activation

application

'application' => 'appnetos-docs',

The identifier must exactly match the configuration basename, excluding an optional environment suffix. For example, appnetos-docs.php and appnetos-docs.docker.php both describe appnetos-docs when APPNETOS_ENVIRONMENT is docker.

active

'active' => false, // Do not resolve this application at runtime.

This key is optional and defaults to true. Inactive applications are still loaded and structurally validated, but their routes are excluded from HTTP matching and an attempt to execute one as a process application is rejected.

Runtime Contexts

contexts

'contexts' => [
    'app',
    'admin',
    'rest',
    'admin-rest',
    'cmd',
    'worker',
],

The array must be non-empty and contain unique, supported context names. The bootstrap currently accepts app, admin, rest, admin-rest, api, admin-api, cmd, and worker. The api and admin-api contexts are reserved for planned functionality; listing them here does not imply their complete runtime implementations are available.

default_context

'default_context' => 'app',

This value is mandatory and must name a context declared in contexts. It is part of the validated application definition; HTTP route selection still follows the explicit host and slug rules, rather than automatically selecting this value for every unmatched request.

base_contexts

'base_contexts' => [
    'app'        => 'app',
    'admin'      => 'admin',
    'rest'       => 'app',
    'admin-rest' => 'admin',
    'cmd'        => 'admin',
    'worker'     => 'admin',
],

Every declared context requires exactly one mapping to an APPNETOS base context: app or admin. Unknown context keys in the mapping are invalid. Both process contexts, cmd and worker, must map to admin. These mappings determine which base-context resources subsequent bootstrap layers use.

Process contexts

cmd and worker must not have entries in routes. Every other declared context must have an HTTP route.

HTTP Route Configuration

Routes are keyed by their declared runtime context. Each HTTP route specifies a slug, a host scope, or both. The examples below illustrate different configurations; they are not intended to be combined verbatim.

Slug-based routing

'routes' => [
    'app' => [
        'slug' => 'docs',
        'hosts' => [],
    ],
],

The first request path segment docs selects this context on an unreserved host. An empty hosts array does not override routes that explicitly reserve the current host.

Host-based root routing

'routes' => [
    'app' => [
        'slug' => '',
        'hosts' => [
            'docs.appnetos.com',
        ],
    ],
],

An empty slug defines the root route for its host scope, including application-internal paths. A host-only route may omit slug; the bootstrap treats it as empty during resolution.

Multiple contexts on one host

'contexts' => ['app', 'admin', 'admin-rest'],
'default_context' => 'app',
'base_contexts' => [
    'app'        => 'app',
    'admin'      => 'admin',
    'admin-rest' => 'admin',
],
'routes' => [
    'app' => [
        'slug' => '',
        'hosts' => ['example.com'],
    ],
    'admin' => [
        'slug' => 'admin',
        'hosts' => ['example.com'],
    ],
    'admin-rest' => [
        'slug' => 'rest',
        'hosts' => ['example.com'],
    ],
],

Within the same eligible host scope, matching non-empty slugs take priority over an empty root slug. Thus /admin and /rest select their respective contexts, while other paths can be handled by the root application route.

hosts normalization and ports

'hosts' => [
    'docs.appnetos.com',
    'localhost:20000',
],

Host names are normalized to lowercase and duplicates are rejected. Bare hosts match any port; a configured host:port requires the corresponding port. The validator also accepts http:// or https:// URLs, converting them into normalized host and port values. For reverse-proxy deployments, bare host names are generally preferable when the external protocol is managed by the proxy. Paths, query strings, fragments, and user credentials are not valid route hosts.

HTTP Resolution Order and Conflicts

Priority Behavior
1. Active applications Only active application routes are eligible for matching.
2. Explicit host scope Routes registered for the current host are considered first. Their presence reserves that host.
3. Non-empty slug A matching first URI segment wins within the eligible scope.
4. Empty slug The root route handles the request when no non-empty slug matches in that scope.
5. Unreserved hosts Only when the current host has no explicit host routes may routes with hosts: [] be considered.
6. Core fallback When no application route matches, APPNETOS uses the Core app context; later handling may produce a 404.

Two active routes cannot register the same slug in overlapping explicit host scopes, or both register the same slug without hosts. The same slug is permitted on disjoint host scopes. An explicitly reserved host excludes hostless routes even when none of its configured slugs matches the request.

Environment-Specific Application Configuration

The bootstrap discovers PHP configuration files exclusively in APPNETOS_PLATFORM/application and selects the file matching APPNETOS_ENVIRONMENT when available.

platform/application/
├── appnetos-docs.php
├── appnetos-docs.docker.php
├── appnetos-dns-control.php
└── appnetos-dns-control.production.php
// Environment Bootstrap has already defined:
APPNETOS_ENVIRONMENT === 'docker';

// Application Bootstrap selects:
// platform/application/appnetos-docs.docker.php
// instead of platform/application/appnetos-docs.php
Files available Environment Selected file
Default + matching environment file docker appnetos-docs.docker.php
Default only docker appnetos-docs.php
Matching environment file only docker appnetos-docs.docker.php
Default + non-matching environment file docker appnetos-dns-control.php

Process and Core Command Resolution

For application commands and workers, RuntimeBootstrap has already populated the requested application and process context. ApplicationBootstrap verifies that the application exists, is active, declares the requested cmd or worker context, and maps that context to the admin base context.

'contexts' => ['app', 'cmd', 'worker'],
'default_context' => 'app',
'base_contexts' => [
    'app'    => 'app',
    'cmd'    => 'admin',
    'worker' => 'admin',
],
'routes' => [
    'app' => [
        'slug' => 'example',
        'hosts' => [],
    ],
    // No HTTP routes for cmd or worker.
],

APPNETOS Core commands have a separate process branch. They execute without a selected application and use the Core admin base context. Application-specific commands must resolve an installed, active application.

RuntimeState Integration and Validation

The bootstrap stores the validated application registry and reserved non-empty route slugs in RuntimeState. Successful resolution then sets the active application, context, base context, and HTTP context slug as appropriate. Subsequent bootstrap steps use this state; the application configuration is not rediscovered by each later component.

Invalid configuration structures stop startup with an exception. Examples include an identifier that differs from its filename, unsupported or duplicate contexts, missing mappings, process contexts mapped to app, missing HTTP routes, invalid hosts, and conflicting active route slugs.

Application Customization and Update Safety

This distinction does not change the bootstrap lookup location: ApplicationBootstrap reads the installed runtime configuration from platform/application/; it does not load installation templates from ./custom/ or <application>/.files/ during this step.

Next Steps

Previous

Runtime

Explore Runtime

Next

CORS

Explore CORS