omnibase/forge

Installation

Requirements

• PHP 8.2 or later, ext-zip;
• doctrine/orm 2.15 or 3;
• omnisense/omnibase 3.0 or 4.0, omnibridge/symfony 1.x, omnibase/admin, omnibase/marketplace;
• git/git-bundle 1.x, with the php-git2 extension (ext-git2), to read the repositories (releases, the project's history);
• omnisense/omnistate with omnistate/annuaire-entreprises: they turn on the marketplace's company register, which checks the SIRET numbers typed in quote requests;
• Symfony 6, 7 or 8 (config, dependency-injection, form, http-kernel, security-bundle).

The bundle

composer require omnibase/forge:dev-main

// config/bundles.php
Omnistate\Bridge\Symfony\OmnistateBundle::class => ['all' => true],
Base\Forge\ForgeBundle::class => ['all' => true],

The routes

# config/routes.yaml
forge_controller:
    resource: "@ForgeBundle/src/Controller"
    type: attribute
    prefix: /

The configuration

Every key is optional (Configuration reference):

# config/packages/forge.yaml
forge:
    storage_dir: '%kernel.project_dir%/var/storage/forge'          # release archives, never under public/
    repositories_dir: '%kernel.project_dir%/var/storage/repositories'
    accel_prefix: '/_protected/forge/'   # nginx internal location; empty: PHP streams the file
    download_ttl: 600                    # seconds a signed link stays valid
    support_store: support               # marketplace store selling hour packs and quotes
    software_store: logiciels            # marketplace store selling licence offers
    hourly_rate: 6000                    # default rate of a quote line, in cents
    low_balance_minutes: 120             # below this, forge:hours:low-balance reminds the client
    contact_email: '%env(MAILER_CONTACT)%'   # where quote requests are mailed

To open each client their own repositories in git/git-bundle's viewer:

# config/packages/git.yaml
git:
    access_role: ROLE_USER
    repository_attribute: GIT_VIEW       # Base\Forge\Security\Voter\GitRepositoryVoter

Every project and piece of software with a repository shows up in the viewer through Base\Forge\Git\ForgeRepositoryProvider.

nginx

The archives are handed out through an internal location:

location /_protected/forge/ {
    internal;
    alias /srv/app/var/storage/forge/;
}

How a purchase is delivered

omnibase/marketplace's Checkout::confirm() dispatches OrderPaidEvent, and Base\Forge\EventSubscriber\OrderPaidSubscriber delivers the order:

Delivery is idempotent per order reference. Bank transfers (the manual gateway) stay pending until someone in the back office posts to forge_admin_order_paid, which confirms the order.

Licence keys (glk_...) are generated by their owner from /compte/licences and shown once; only their SHA-256 is stored.

The cron

The templates

They extend the site's layout1.html.twig, use forge-* classes for the site to style, and are overridden in templates/bundles/ForgeBundle/.

Games and applications

A piece of software has a kind (Software::$kind, SoftwareKind): package (Composer, Unity), game or app. A game's or an application's releases carry builds, one per platform (Platform: webgl, windows, macos, linux, android), made elsewhere - Unity, a CI - and attached to the release:

bin/console forge:artifact:attach <slug> <version> <platform> <file> [--publish] [--changelog "..."]

or from the back office (Releases > Builds). The release is made when it does not exist yet: a game need not come from a repository's tags. A build replaces the platform's previous one; its sha256 is taken on the way in.

Free and paid games

• A free game is played in the browser (its WebGL build, in its page) and downloaded freely, its builds per platform.
• A paid game is downloaded once bought (a licence offer, as any licensed software), its builds per platform through signed links. It is played in the browser only when the studio opens a playable preview of it (Software::$playablePreview, off by default; "Playable preview" in the back office) - then by anyone, as a demo.

The game's page

The software page (/telechargements/<slug>) of a game shows, above its versions:

• Play, when its newest version has a WebGL build and the game plays in the browser (free, or a paid game with its playable preview open). Nothing of the game loads before Play is pressed: bundles/forge/js/play.js then frames /play/<slug>/<version>/ in the page (without JavaScript the link opens it on its own), with a full-screen button. A game that stores nothing before it is played leaves the site's cookie panel untouched; build it with Data Caching off (Player Settings > Publishing Settings) so that Unity writes nothing to the browser's IndexedDB either.
• Its trailer (an uploaded video) and its screenshots (uploads, in their order), both set in the back office.
• Under each version, its changelog and its builds: a signed, short-lived link each (/telechargements/<slug>/<version>?format=<platform>), its size and its sha256.

WebGL builds: compression

/play/<slug>/<version>/<path> (PlayController, WebglBuilds) unpacks the build once, beside its zip in the storage, and serves each file with what Unity's loader needs:

• *.br with Content-Encoding: br, *.gz with Content-Encoding: gzip;
• the type of what they hold: application/wasm for the .wasm (the browser then compiles it as it streams in), application/javascript for the .js, application/octet-stream for the .data.

So the browser decompresses the build, not Unity's JavaScript: build with Brotli (Unity's default; Brotli needs HTTPS, which the site is) and leave Decompression Fallback off - it would make the loader bigger and slower for nothing. The headers are set by PHP, so they do not depend on the web server's configuration. A build made with the fallback (.unityweb files) is served too, as it is.

The frame is the stage's size (16:9, the page's width): build with a WebGL template whose canvas fills its window (width: 100%; height: 100%, matchWebGLToCanvasSize: true) - Unity's Default template draws a fixed 960x600 canvas, cropped in the frame on a phone. The sample game's Assets/WebGLTemplates/Forge/index.html is one: a canvas, a loading bar, nothing else.

A paid game without a playable preview is not played here (403; the staff may, to check a build), its files then cached by the browser alone (Cache-Control: private).

Checking a licence from the game

com.glitchr.licensing, a Unity package served by the forge's own registry (see upm.md), calls the licence API (see licensing.md) and checks the signed token offline.

Licensing a game or an application

How a licensed piece of software - a Unity game, a desktop application such as Switch for Coder - checks that it may run, machine by machine.

The model

• A licence (License) covers one software for so long (expiresAt, null: perpetual) and its releases until a date (updatesUntil).
• It has seats (seats), an e-mail each (LicenseSeat): the buyer's own first, the others given from their account or from the back office. Each seat has its own key (glk_…), made from the account page.
• Each seat may activate the software on machinesPerSeat machines (2 by default, set on the offer). Its holder frees a machine from their account ("Mes licences"); the studio from the back office (Machines activées).

The API

JSON over HTTPS, no session: the seat's key is the credential.

POST /api/licenses/activate

At the first start, and then whenever the token is about to run out.

{
  "key": "glk_XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX",
  "software": "switch-for-coder",
  "machine": "<a stable identifier of this machine>",
  "name": "MacBook Air de Camille",
  "platform": "macos",
  "version": "1.4.0"
}

• software: the software's slug on the site - a key opens only its own.
• machine: stable across restarts and updates. Unity: SystemInfo.deviceUniqueIdentifier; macOS: the IOPlatformUUID; Windows: MachineGuid. The site stores only its SHA-256.
• name, platform, version: shown to the holder, to recognise the machine.

Answers:

Activating an already active machine takes no new place: call it as often as needed.

POST /api/licenses/release

{"key": "…", "machine": "…"} - the machine frees its own place (an uninstall, a "deactivate" menu). {"status": "released"} or {"status": "not_activated"}.

GET /api/licenses/public-key

{"algorithm": "Ed25519", "public_key": "<base64>"} - ship it in the software rather than fetching it: a key fetched at run time could be swapped.

The token, checked offline

token = base64url(payload JSON) + "." + base64url(Ed25519 signature of the payload JSON)

The software runs when, all of them:

1. the signature verifies with the public key it ships with;
2. software is its own slug;
3. machine equals the SHA-256 (hex) of its own machine identifier;
4. now is before valid_until (UNIX time) - past it, activate again, online;
5. for a version gate: its release date is before updates_until, when set.

valid_until is FORGE_LICENSE_GRACE_DAYS (30 by default) after the last activation, never beyond the licence's expiry: a machine offline for longer must come back online once; a revoked licence or a freed machine stops at the latest then.

Unity (C#)

The com.glitchr.licensing package (served by the forge's Unity registry, see upm.md; source: github.com/glitchr-studio/unity-licensing) does all of it - LicenseClient.ActivateAsync(), LicenseClient.Check() -, with Ed25519 in managed code. By hand, with an Ed25519 library:

string[] parts = token.Split('.');
byte[] json = Base64Url.Decode(parts[0]);
byte[] signature = Base64Url.Decode(parts[1]);
bool genuine = Ed25519.Verify(signature, json, PublicKey);
var payload = JsonUtility.FromJson<LicensePayload>(Encoding.UTF8.GetString(json));
string machine = Sha256Hex(SystemInfo.deviceUniqueIdentifier);
bool runs = genuine && payload.software == "my-game" && payload.machine == machine
    && DateTimeOffset.UtcNow.ToUnixTimeSeconds() < payload.valid_until;

Swift (macOS)

CryptoKit verifies Ed25519 natively:

let parts = token.split(separator: ".").map(String.init)
let json = Data(base64URLEncoded: parts[0])!, signature = Data(base64URLEncoded: parts[1])!
let key = try Curve25519.Signing.PublicKey(rawRepresentation: Data(base64Encoded: publicKey)!)
let genuine = key.isValidSignature(signature, for: json)
let payload = try JSONDecoder().decode(LicensePayload.self, from: json)
let machine = SHA256.hash(data: Data(platformUUID.utf8)).map { String(format: "%02x", $0) }.joined()
let runs = genuine && payload.software == "switch-for-coder" && payload.machine == machine
    && Date().timeIntervalSince1970 < payload.valid_until

The signing key

bin/console forge:license:keypair makes a pair. The secret goes in the vault (bin/console secrets:set FORGE_LICENSE_SIGNING_KEY), the public key in the software. A new pair makes every token issued so far unverifiable: ship the new public key first.

Signed download links

An artifact is downloaded through a link signed by omnisense/omnibase's Base\Service\DownloadLinks (route forge_download_file, valid forge.download_ttl seconds; the Composer index signs its links for thirty days). Who may download was checked when the link was handed out (the licence); the download action only checks the signature. The forge no longer has a DownloadLinks of its own.

The project board

A project (Base\Forge\Entity\Project) has a board: four columns (Base\Forge\Enum\CardColumn: to do, in progress, in review, delivered) and its cards (Base\Forge\Entity\Card), which the client and the studio both move. The bundle ships the whole of it: the page, the move, the script and the stylesheet.

What it gives

Who sees a project and who moves its cards is ProjectVoter's: its client and the staff. A delivered project (ProjectStatus::DONE) is read-only for its client: the page carries no token and its script leaves it alone.

In a page of one's own

{% include '@Forge/client/project/_board.html.twig' with {project: project} %}

Run bin/console assets:install once, as for any bundle with public files.

The script needs nothing called: every [data-forge-board] carrying a data-token is taken in charge, the ones a page brings in later too (a page swapped in without a reload). It announces what happens on the board's element:

A refused move is said with SweetAlert when the page has it (window.Swal), in a role="alert" paragraph of the board otherwise.

Its look

The stylesheet sets no colour of its own beyond defaults; a site sets these on .forge-board or above:

.forge-board {
    --forge-board-column: var(--my-surface-soft);
    --forge-board-card: var(--my-surface);
    --forge-board-soft: var(--my-ink-soft);
    --forge-board-radius: .75rem;
    --forge-board-backlog: #8a8f98;
    --forge-board-progress: #1c7ed6;
    --forge-board-review: #f08c00;
    --forge-board-done: #2f9e44;
}

A card carries is-backlog, is-progress, is-review or is-done; a column being dragged over, is-over; the card in hand, is-dragging.

An application that had its own board

An application that wrote its own board before the bundle had one (a controller renumbering the cards, a Stimulus controller, the markup in its dashboard) keeps working as it is: the bundle adds routes, a template and a service, and changes nothing that was there. To move over:

1. In the dashboard's template, replace the board's markup with the include above.
2. Delete the application's own move action and its script; Base\Forge\Service\Board is what the action called by hand.
3. Rename what the stylesheet styled: .kanban is .forge-board, .kanban-column .forge-board-column, .kanban-card.kanban-review .forge-board-card.is-review - or drop those rules and set the custom properties.

Pipelines

A pipeline (Base\Forge\Entity\Pipeline) is one run of a project's checks on a commit - its tests, its build, its deployment -, wherever it ran: a forge's CI, a script. It has stages in order (Stage), each with its jobs (Job). The bundle records what happened and shows it; it runs nothing itself.

Recording a run

use Base\Forge\Entity\Pipeline;
use Base\Forge\Enum\PipelineStatus;

$pipeline = $pipelines->findOneBySource('gitlab', '4821')            // the same run, brought up to date
    ?? (new Pipeline($project, 'main', $sha))->setSource('gitlab', '4821');
$pipeline->setUrl('https://gitlab.example.org/site/-/pipelines/4821');

$pipeline->stage('install')->job('composer', PipelineStatus::SUCCESS);
$pipeline->stage('test')->job('phpunit', PipelineStatus::RUNNING)->setUrl('https://gitlab.example.org/site/-/jobs/9917');
$pipeline->stage('test')->job('lint', PipelineStatus::FAILED)->setAllowFailure(true);
$pipeline->stage('deploy')->job('production', PipelineStatus::MANUAL)->setNeeds(['phpunit']);

$entityManager->persist($pipeline);
$entityManager->flush();

stage() and job() find the one of that name or make it, so the same lines bring a run up to date as its jobs move on. source and its id name a run once (a unique pair).

A status (Base\Forge\Enum\PipelineStatus: pending, running, success, warning, failed, canceled, skipped, manual) is set on jobs only. A stage is what its jobs say and a pipeline what its stages say - failed as soon as one failed, running while one runs, waiting on a manual step - unless the pipeline's own status was set by hand (setStatus()). A job allowed to fail that failed counts as a warning.

The bundle has no listener for a CI's webhooks yet: what records the runs (a webhook's controller, a command the CI calls) is the application's for now.

Seeing it

{% include '@Forge/client/project/_pipelines.html.twig' with {project: project, limit: 3} %}

The graph

A run is drawn by @glitchr/graphjs, which omnibase/admin vendors and its layout loads on every page of the back office: a node per job - its stage under its name, in the colour of its status -, ranked by stage, an edge from each job it waits for (the ones needs names, or every job of the stage before). The template writes it in the page (data-graph, the pipeline preset), so the jobs still read, in order, without the script. Outside the back office the include loads the library itself, once per page (assets: false when the page already does).

Base\Forge\Service\PipelineGraph::data($pipeline) returns the same graph as data - {nodes: [{id, label, sub, rank, state, href, title}], edges: [{from, to}]} - for Graph.setData(), when a page follows a run that is still moving:

const graph = Graph.get(document.querySelector('#forge-pipeline-12'));
graph.setState('job-31', 'success');

Tables

forge_pipeline, forge_pipeline_stage, forge_pipeline_job: an application that updates the bundle writes their migration (doctrine:migrations:diff).

The hub

The forge serves, beside its Unity registry (upm.md), what the hub clients read: the Unity window com.glitchr.hub (Window > Glitch Art Hub, in the editor) and the desktop hub. A client is pointed at one URL, the hub manifest, and finds there the brand, the sources and whether something can be bought.

The manifest: GET /upm/-/hub.json

{
  "version": 1,
  "name": "Glitch Art",
  "logo": "https://glitchr.io/assets/images/brand/monkey.png",
  "color": "#fc6875",
  "sources": [
    {
      "name": "Glitch Art",
      "type": "upm",
      "url": "https://glitchr.io/upm",
      "scopes": ["com.glitchr"],
      "catalog": "https://glitchr.io/upm/-/hub/catalog.json"
    }
  ],
  "games": "https://glitchr.io/upm/-/hub/catalog.json",
  "checkout": {
    "device": "https://glitchr.io/upm/-/hub/device",
    "token": "https://glitchr.io/upm/-/hub/token"
  },
  "licenses": {
    "list": "https://glitchr.io/upm/-/hub/licenses",
    "activate": "https://glitchr.io/api/licenses/activate",
    "release": "https://glitchr.io/api/licenses/release"
  }
}

• sources: UPM registries (type: upm, url, scopes, an optional catalog) or Git packages (type: git, url). A client adds them to a project's Packages/manifest.json as scoped registries or Git dependencies.
• checkout: present when the hub sells. A client shows "Buy" only for a source whose manifest has it - a static hub (a copied template on GitHub Pages) never does.

It is configured in config/packages/forge.yaml:

forge:
    hub:
        name: 'Glitch Art'
        logo: '/assets/images/brand/monkey.png'   # or an absolute URL
        color: '#fc6875'
        scopes: ['com.glitchr']                    # empty: those of the Unity packages
        checkout: true

The catalogue: GET /upm/-/hub/catalog.json

What a shop window shows and the Package Manager's search does not:

• packages: every published Unity package, the paid ones too, each with its versions and their changelog, its picture and screenshots, its page, pricing (free or licensed), its offers (id, title, price in cents, currency, seats, months) and installable - true when the caller's licence key (Authorization: Bearer, as for the registry) covers it;
• games: every published game, with play (the address of its WebGL build) only when it is played in the browser - a free game, or a paid one whose playable preview is open (games.md) -, its platforms and its offers.

Buying: the device flow

The editor has no session on the site. It is linked to its user's licences the way a television is linked to an account (OAuth's device flow, RFC 8628):

1. POST /upm/-/hub/device {"item": "com.glitchr.licensing"} answers a device_code (kept by the editor), a user_code (ABCD-EFGH, shown to the user) and verification_uri_complete, which the editor opens in the browser.
2. On that page (/hub/link), signed in, the user sees the code and the item's offers; they buy one through the shop's cart and checkout, in a tab of their own, then come back and press "Link this editor".
3. Meanwhile the editor asks POST /upm/-/hub/token {"device_code": ...} every interval seconds: authorization_pending, slow_down or expired_token (400) until the user links it; then, once, {"key", "email", "registry"}.

The key is a new key of one of the user's seats (the seat's previous key stops working); it opens every licence of that e-mail, as for Composer. The editor stores it as the registry's token in the user's ~/.upmconfig.toml, never in the project. The codes live ten minutes, in the cache only.

Licences: GET /upm/-/hub/licenses

With the key as a Bearer: the holder's e-mail and each valid licence - its software (slug, which the licence API asks for, its name, its UPM name, its page), status, expiry, updates, seats, machines per seat, and the machines of that holder's seat, each with the SHA-256 of its identifier (machine), which a client compares with its own to say "this machine". A client activates and releases itself through the addresses the manifest lists under licenses (/api/licenses/activate, /api/licenses/release, see licensing.md).

The Unity registry

The forge serves its Unity packages to Unity's Package Manager as a scoped registry: the npm registry protocol, under /upm, beside the Composer repository (/composer/packages.json) it mirrors. A piece of software is a Unity package when it has a UPM name (Software::$upmName, com.glitchr.<name>) and a git repository whose tree at each tag is the package: package.json at its root, every asset with its .meta.

What it serves

This is what Unity 6 (6000.0) was seen asking, on 2026-10-26, from a probe registry: the search, page after page until one comes back empty (/-/all when the search is a 404), then the package document, then HEAD and GET of the tarball - every request with the registry's token from .upmconfig.toml as Authorization: Bearer <token>.

The tarball

ArtifactBuilder::buildUpm() writes it from the tree at the tag, as npm does: a gzip'd ustar archive, every file under package/, its package.json carrying the package's UPM name and the release's version (whatever the tag's file said). Its sha256, sha1 and sha512 are stored on the artifact (format upm). forge:release:sync builds it with the zip for each new tag; "Build" in the back office rebuilds both.

Free and licensed packages

A free package is listed and installed by anyone. A licensed one only by the holder of a valid licence covering that version (License::covers()), as for Composer: the licence key goes in the user's ~/.upmconfig.toml (%USERPROFILE%\.upmconfig.toml on Windows):

[npmAuth."https://glitchr.io/upm"]
token = "glk_XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX"
alwaysAuth = true

The key alone is enough: it names its seat, whose e-mail names every licence it holds. _auth = "<base64 of e-mail:key>" (Basic) works too, the e-mail then checked against the seat's.

Each tarball handed out is one Download row, channel upm, counted against the licence that covered it (a HEAD is not counted).

The host's firewall

The registry reads the Authorization header itself. A firewall of the host that authenticates Bearer tokens on every path (Symfony's access_token, as on the main firewall of omnibase's sites) would take the licence key for one of its own tokens and refuse it before the registry sees it (401 invalid_token). Keep /upm out of it, before that firewall:

# config/packages/security.yaml
security:
    firewalls:
        upm:
            pattern: ^/upm/
            stateless: true
            security: false

In the project

"scopedRegistries": [
  {"name": "Glitch Art", "url": "https://glitchr.io/upm", "scopes": ["com.glitchr"]}
],
"dependencies": {
  "com.glitchr.licensing": "1.0.0"
}

The software page shows these lines for each Unity package.

A development site

A forge run locally behind a self-signed certificate (https://localhost:8453) is refused by the Package Manager until it trusts that certificate: give it the certificate as an extra certificate authority, caFile in the Package Manager's configuration file (Unity manual, "Configure your network for Package Manager"):

caFile = "/path/to/localhost.crt"

Quotes

A client asks for a quote from the site (/support/devis), the studio prices it in the back office - lines of hours at a rate, a discount, a date - and sends it (/admin/forge/quote/{id}/send); the client reads it at /devis/{token}, accepts it, and pays a one-off HourPack holding its hours. Paid, the hours are credited and the quote marked paid (EventSubscriber\OrderPaidSubscriber).

What is omnibase/marketplace's

Since the marketplace's business quotes, what every quote is lives there, and the forge keeps only its hours:

hasSomethingToSell() is the hours: a quote without any cannot be accepted.

Upgrading

Nothing in the database: forge_quote and forge_quote_line keep their columns (the schema generated before and after is the same). An application using Base\Forge\Form\QuoteRequestType or Base\Forge\Model\QuoteRequest directly uses the marketplace's instead; Base\Forge\Enum\QuoteStatus keeps working (an alias).

Configuration reference

The forge tree

Dumped with Symfony's YamlReferenceDumper from Base\Forge\DependencyInjection\ForgeConfiguration:

forge:

    # Where release archives are written. Never under public/: they are handed out by the download controller.
    storage_dir:          '%kernel.project_dir%/var/storage/forge'

    # Where the repositories of projects and software that are not in git.repositories are cloned (<name>.git).
    repositories_dir:     '%kernel.project_dir%/var/storage/repositories'

    # The nginx `internal` location aliasing storage_dir (X-Accel-Redirect). Empty: PHP streams the file itself.
    accel_prefix:         /_protected/forge/

    # How long a signed download link stays valid, in seconds.
    download_ttl:         600

    # The market store (slug) hour packs and accepted quotes are sold from.
    support_store:        support

    # The market store (slug) licence offers are sold from.
    software_store:       logiciels

    # Default hourly rate of a quote line, in cents.
    hourly_rate:          6000

    # Below this balance a client is reminded to top up (forge:hours:low-balance).
    low_balance_minutes:  120

    # Where quote requests are mailed. Null: they are only listed in the back office.
    contact_email:        null

    # The hub manifest (/upm/-/hub.json) the Unity window (com.glitchr.hub) and the desktop hub read: the brand and the sources. See docs/hub.md.
    hub:

        # The hub's name, shown by the clients.
        name:                 Forge

        # Its logo: an absolute URL, or a path on this site.
        logo:                 null

        # Its accent colour, #rrggbb.
        color:                null

        # The scopes of the Unity registry (com.glitchr): those of the Unity packages when empty.
        scopes:               []

        # Whether the clients offer to buy: the licensed packages' offers, bought on this site and linked to the editor by a device code.
        checkout:             true

Each key is a container parameter (%forge.storage_dir%, %forge.hub.name%...).

Reference

Routes

Commands

Twig

Listeners

Enums

Back office screens

Projects, cards, time entries, pipelines, project reviews, software, releases, downloads, licences, licence offers, seats, activations, hour packs, hour credits, hour refunds and quotes, each a CRUD of omnibase/admin.

Testing

Running the suite

vendor/bin/phpunit                                   # standalone
vendor/bin/phpunit -c vendor/omnibase/forge          # from a host

In omnisense/omnibase-harness, mounting the checkout in place of the installed package:

docker run --rm --network none \
    -v "$PWD":/srv/demo/vendor/omnibase/forge:ro \
    omnisense/omnibase-harness:latest test forge

On this checkout, in the harness:

OK (48 tests, 460 assertions)

What the tests cover