169 lines
12 KiB
Markdown
169 lines
12 KiB
Markdown
# Administrator Guide
|
|
|
|
This guide covers administration inside Conductor: accounts, sessions, stored credentials, publications, and execution history. For Docker, TLS, configuration keys, backups, recovery, and upgrades, use the [Installation Guide](INSTALL.md) and [Operations Guide](OPERATIONS.md).
|
|
|
|
## Administrator scope
|
|
|
|
Conductor has global roles rather than per-project or per-application permissions.
|
|
|
|
| Principal | Access |
|
|
|---|---|
|
|
| Anonymous visitor | Active public applications and their anonymous actions only. |
|
|
| User | Public and restricted applications in the catalog; own password change. |
|
|
| Administrator | All user access plus project authoring, validation, action testing, credentials, execution history, publishing, and user management. |
|
|
|
|
The backend enforces these boundaries even if someone constructs an API request directly. Conductor v1.1.0 does not provide groups, custom roles, per-application assignments, self-registration, email invitations, or email-based password recovery.
|
|
|
|
## Initialize a new installation
|
|
|
|
1. Confirm the host operator has finished the deployment, configured HTTPS, and received a healthy response from `/api/health`. Independent self-hosters can follow the [public installation guide](INSTALL.md).
|
|
2. Open the Conductor HTTPS URL in a browser.
|
|
3. On **Set up Conductor**, enter a unique username and a password of at least 12 characters. Display name and contact email are optional.
|
|
4. Select **Create administrator**. Conductor creates the account and signs it in.
|
|
5. Open **Users** and create a second administrator for recovery before authoring production applications.
|
|
|
|
There are no default credentials. The browser setup is available only while the database contains no users; it closes permanently after the first account is created. Concurrent setup attempts can create at most one first administrator.
|
|
|
|
If browser setup cannot be used, the host operator can perform the explicit empty-installation bootstrap in [Administrative bootstrap and recovery](OPERATIONS.md#administrative-bootstrap-and-recovery).
|
|
|
|
## Manage users and sessions
|
|
|
|
Open **Users** to perform account administration.
|
|
|
|
### Create an account
|
|
|
|
Enter a unique username, optional display name and contact email, a temporary password of at least 12 characters, and the `User` or `Admin` role. Communicate the temporary password through an approved private channel.
|
|
|
|
### Change an account
|
|
|
|
- Change **Role** to promote or demote an account.
|
|
- Toggle **Enabled** to allow or block authentication.
|
|
- Edit display name or contact email and leave the field to save it.
|
|
- Select **Reset password** to set and confirm a new password.
|
|
- Select **Revoke sessions** to sign the account out everywhere.
|
|
|
|
Disabling an account, changing its role, resetting its password, or explicitly revoking sessions invalidates its existing sessions. Conductor refuses to disable or demote the last enabled administrator.
|
|
|
|
Users change their own password beneath the application catalog. That operation rotates the current session and revokes their other sessions. Administrators can reset their own account from **Users**, but should keep another working administrator available before doing so.
|
|
|
|
Account deletion is not exposed in v1.1.0. Disable an account when access should be retained only for historical attribution.
|
|
|
|
## Manage stored credentials
|
|
|
|
Open **Actions & Bindings**, then expand **Secrets**.
|
|
|
|
Supported credential types are:
|
|
|
|
- Basic authentication username and password;
|
|
- Bearer token;
|
|
- API-key header name and value; and
|
|
- API-key query-parameter name and value.
|
|
|
|
To create a credential, select **Add secret**, choose the type, enter a descriptive name and its required fields, and save. Conductor returns only metadata after creation; the stored value cannot be viewed again.
|
|
|
|
To rotate a credential, expand it and select **Replace value**. Enter the complete new credential. Saved project actions retain the same opaque reference.
|
|
|
|
To remove a credential safely:
|
|
|
|
1. Find every saved project and active publication that uses it.
|
|
2. Remove or replace the reference in each source project, then save the project.
|
|
3. Republish each application that should remain live, or unpublish it. Published snapshots are immutable and can retain the old reference until this step is complete.
|
|
4. Expand the credential and select **Delete**.
|
|
|
|
Deletion is blocked by references in saved projects, but v1.1.0 does not perform that same check against immutable published snapshots. Do not delete first and leave a live restricted application with a missing credential.
|
|
|
|
Credential values are encrypted with AES-256-GCM using `CONDUCTOR_SECRET_KEY`. The browser and project JSON receive only opaque secret references, and an existing value can never be retrieved through Conductor. A usable disaster-recovery archive must contain both the database and its matching key. See [Backup](OPERATIONS.md#backup).
|
|
|
|
## Publish and withdraw applications
|
|
|
|
Open **Publishing** after saving and validating a source project.
|
|
|
|
1. Select the source project.
|
|
2. Enter a display name and unique URL slug.
|
|
3. Choose a visibility:
|
|
- **Restricted to users** requires an enabled signed-in account.
|
|
- **Public** permits anonymous access and is accepted only when every action uses anonymous authentication.
|
|
4. Select **Publish**.
|
|
5. Use **Open app** to verify the default page and at least one direct page URL.
|
|
|
|
Publishing stores an immutable snapshot. Editing or saving the source project does not change the live application. Select **Republish** to atomically replace the snapshot with the current valid saved project and increase its version.
|
|
|
|
Select **Unpublish** to make the application unavailable without deleting the source project. Republish it to restore access. Active publications prevent deletion of their source project through the backend API.
|
|
|
|
Published routes are:
|
|
|
|
```text
|
|
/apps/<app-slug>
|
|
/apps/<app-slug>/<page-slug>
|
|
```
|
|
|
|
Restricted visibility applies to the whole application. Page navigation settings are not authorization rules.
|
|
|
|
## Review execution history
|
|
|
|
Open **Execution History** to inspect recent REST proxy activity. Records persist across restarts and include safe request identity, timing, outcome, upstream status when available, response size, and a bounded redacted preview.
|
|
|
|
Conductor retains the newest 1,000 executions globally. It does not store request or response headers, cookies, credentials, raw sensitive query values, DNS answers, or stack traces. Treat this as bounded troubleshooting history, not as an immutable enterprise audit log.
|
|
|
|
**Clear history** permanently removes all execution records. Back up the installation first if those records are needed for later analysis.
|
|
|
|
## Proxy and internal destinations
|
|
|
|
Project authors can call public `http` and `https` endpoints that pass Conductor's destination and request policy. Private, loopback, link-local, metadata, and other unsafe address ranges are blocked by default.
|
|
|
|
An in-application administrator cannot weaken that policy. A host operator may add a reviewed exact origin to `CONDUCTOR_PROXY_INTERNAL_ORIGINS`; wildcards, URL paths, embedded credentials, and IP literals are not accepted. Use [Production configuration](OPERATIONS.md#production-configuration).
|
|
|
|
## Recover administrative access
|
|
|
|
Try these options in order:
|
|
|
|
1. Ask another enabled administrator to reset the account's password, enable it, restore its role if appropriate, and revoke old sessions.
|
|
2. If every administrator is inaccessible, ask the host operator to use the guarded recovery command in [Administrative bootstrap and recovery](OPERATIONS.md#administrative-bootstrap-and-recovery).
|
|
3. If application data is damaged or missing, follow the full [restore procedure](OPERATIONS.md#restore) instead of creating unrelated accounts.
|
|
|
|
Operator recovery can target only an existing local administrator. It cannot elevate a user or create an additional administrator after first-run setup.
|
|
|
|
## Routine administration checklist
|
|
|
|
- Keep at least two enabled administrators with independently controlled credentials.
|
|
- Review active publications and confirm public applications contain no credential-backed actions.
|
|
- Rotate upstream credentials using **Replace value**, then test the affected actions.
|
|
- Review execution failures without copying sensitive data into tickets or screenshots.
|
|
- Confirm scheduled backups complete, copy them off-host, and periodically test a restore.
|
|
- Install upgrades only from pinned images after reading release notes and taking a backup.
|
|
|
|
For symptom-based help, see [Troubleshooting](TROUBLESHOOTING.md). Product boundaries are summarized in [v1.1.0 limitations](USER_GUIDE.md#v100-limitations).
|
|
|
|
## Security boundaries
|
|
|
|
- Authentication establishes an identity; backend authorization independently checks the account's current enabled state and role on every protected request.
|
|
- Passwords use salted `scrypt` hashes. Sessions are random, server-side, hashed at rest, rotated after sensitive account changes, and protected by secure cookies and CSRF tokens.
|
|
- All authoring, validation, credential, history-management, user-management, and publication-management APIs require an administrator. Hiding navigation in the browser is not the security boundary.
|
|
- Publishing stores an immutable validated snapshot. Public snapshots may use only anonymous actions. Restricted published clients submit runtime values to server-owned action IDs and never receive draft JSON, secret references, authoritative URLs, or authentication configuration.
|
|
- Execution history stores at most 1,000 sanitized records. It excludes request and response headers, cookies, credential values, sensitive query values, DNS answers, private addresses, and stack traces.
|
|
- Conductor does not isolate mutually hostile administrators or protect a host whose backend process, database plus encryption key, or operating system has been compromised.
|
|
|
|
## Included with Skeleton Works
|
|
|
|
Publishing now has separate sections for applications you publish from saved projects and applications installed on the VM. Installed applications appear only after their installer registers them. Use **Open** to launch one and **Configure**, when supplied, for its administration screen. Installed applications do not have Republish or Unpublish controls; their installer owns updates and removal.
|
|
|
|
For the manifest and VM administration commands, see [Included applications](INCLUDED_APPLICATIONS.md). Conductor contains no default Social Scheduler entry.
|
|
|
|
## Application icons and browser titles (v1.1.0)
|
|
|
|
These features are included in Conductor v1.1.0.
|
|
|
|
Conductor uses its blue C-and-baton icon by default. The browser tab shows **Conductor** at home, the screen name while editing (for example, **Publishing · Conductor**), or the application's name (for example, **Workshop Notes · Conductor**).
|
|
|
|
To choose an icon when publishing:
|
|
|
|
1. Open **Publishing** and select the saved project, application name, address and access setting. This identifies the application being published.
|
|
2. Under **Application icon (optional)**, choose a square PNG between 16 and 512 pixels and no larger than 256 KB (262,144 bytes). The preview confirms the image was accepted; leave the field empty to use Conductor's icon.
|
|
3. Select **Publish**, then **Open app**. The application card and browser tab should show the chosen icon and application name.
|
|
|
|
To change an existing application's icon, expand **Application icon** on its Publishing card and choose a PNG. This saves the icon immediately. Select **Use Conductor icon** to reset it. Reload an already-open application tab to see a changed icon. Republish preserves the chosen icon; changing an icon does not publish changes to the source project or change its access setting.
|
|
|
|
Uploads are stored with Conductor's database on the customer VM. They need no S3 service. They are public decorative images, including when assigned to restricted applications, so choose a logo or symbol suitable for public display. Uploading an icon requires an administrator session and the same request protection as other administrative changes.
|
|
|
|
Installed applications receive their name and optional icon from their installer. Their icons are not edited through the project-publication controls. See the [installed-application contract](INCLUDED_APPLICATIONS.md).
|