Install T.E.R.R.A. inside the system your team already uses.

What the customer needs

Create the deployment

1. Open Installation in Asterhelm.
2. Select the project and Test environment.
3. Enter a deployment name.
4. Enter the exact website origin with no page path.
5. Choose the public token endpoint path.
6. Choose Plain PHP, Generic JavaScript or React + PHP.
7. Create the deployment and copy the one-time secret.

Download the protected kit

The ZIP is generated only after Asterhelm verifies the user, role, active entitlement, plan feature and environment. No public ZIP is stored.

asterhelm-terra-install/
├── public/
│   ├── terra-token.php
│   └── terra-test.php
├── private/
│   ├── terra-config.php.example
│   └── .htaccess
├── frontend/
│   ├── terra-embed.js
│   └── TerraEmbed.jsx
├── embed-snippet.html
├── installation-manifest.json
├── CHECKSUMS.txt
└── README-FIRST.txt

Configure the private secret

Copy terra-config.php.example to terra-config.php and paste the one-time secret.

<?php
return [
  'deployment_id' => 'deploy_...',
  'deployment_secret' => 'terra_deploy_test_...',
  'website_origin' => 'https://dashboard.company.com',
  'session_user_id_key' => 'user_id',
  'session_user_role_key' => 'role',
];

Recommended private location

/home/ACCOUNT/terra-private/terra-config.php

If it must remain under public_html, retain the supplied protected folder and .htaccess.

Upload the token broker

Upload public/terra-token.php to the path chosen when the deployment was created.

/home/ACCOUNT/public_html/api/terra-token.php

The supplied file supports common PHP sessions. Change only the marked user-resolution section when required.

$userId = $_SESSION['user_id'] ?? null;
$userRole = $_SESSION['role'] ?? 'member';

Paste TERRA into an authenticated page

<script src="https://api.asterhelm.com/embed/terra.js" defer></script>
<script>
window.addEventListener('DOMContentLoaded', function () {
  AsterhelmTerra.init({
    tokenEndpoint: '/api/terra-token.php'
  });
});
</script>

Asterhelm hosts terra.js centrally so fixes do not require every customer to replace the widget file.

Mount the generated component

Copy frontend/TerraEmbed.jsx into the React application and render it only within the authenticated layout.

import TerraEmbed from './components/TerraEmbed';

export default function AdminLayout() {
  return (<>
    <DashboardRoutes />
    <TerraEmbed />
  </>);
}

The deployment secret must never be placed in frontend environment variables that are bundled for the browser.

Confirm the complete flow

Create a separate Live deployment

1. Switch the project to Live.
2. Create a new Live deployment.
3. Copy the new Live secret.
4. Download a fresh Live kit.
5. Update the private Live configuration.
6. Run the Live evidence and origin checks.

How Asterhelm prevents kit sharing

Copied to another company

If a kit for https://cvbright.com is copied to https://anothercompany.com, Asterhelm returns:

{
  "ok": false,
  "error": {
    "code": "deployment_origin_mismatch",
    "message": "This TERRA deployment is not authorised for this website."
  }
}

Five origin mismatches within ten minutes temporarily block the deployment for fifteen minutes and create Audit Log events.

What happens when access changes

Previously downloaded files remain on the customer server, but they cannot obtain valid tokens after entitlement access stops.

Common installation errors