Skip to main content

Control Panel User Guide

This guide walks portal users through the Cirrus CDN dashboard. It focuses on day-to-day operations such as adding domains, adjusting origin and cache behavior, managing credentials, and checking platform health. Everything described here is available through the web interface served by the control plane (default http://<your-api-host>/).

1. Getting Started​

Sign in​

  1. Navigate to the login page (/login).
  2. Enter your Cirrus CDN username and password.
  3. Click Sign in. A spinning indicator confirms the request; success redirects you to the Sites overview.
  4. If credentials fail, an inline alert appears. Retry or contact an administrator to reset your account.

Tip: The login form lets you toggle password visibility via the eye icon.

Choose language and theme​

Once signed in, use the header controls (top-right):

  • Language switcher toggles between English (EN) and Chinese (ZH). The choice persists locally.
  • Theme toggle cycles through Light, Dark, and System preferences.

Understand the navigation shell​

Every authenticated page shares the same layout:

  • Top header - Quick access to the status console (Grafana link), language/theme controls, notifications placeholder, and account menu (profile + logout).
  • Sidebar / horizontal nav - Primary sections: Sites, Users, Tokens, Settings.
  • Right rail (on wider screens) - Platform status (control plane + edge uptime), context-sensitive information about the currently selected domain, and shortcuts to browse other sites.
  • Content pane - The active feature view.

On mobile, navigation items collapse into chips above the content and the right rail is hidden.

2. Sites: Managing Domains​

Select Sites from the navigation to see all CDN-managed domains.

Sites overview​

  • Metrics cards summarize total sites, cache coverage, average origins, and ACME automation uptake. Numbers update live.
  • Search & filters use the query box to filter domains by substring.
  • Table lists each domain with cache status, origin count, ACME mode, and a chevron to open detailed management tabs.
  • Add Site button opens a guided dialog.

Add a new site​

  1. Click Add Site.
  2. Fill in the domain name (e.g., example.com).
  3. Provide an origin host, port, and protocol (HTTP/HTTPS). Defaults: port 80, weight 1.
  4. Submit. A success toast confirms creation and you are redirected to the Access tab for the new domain.

Domain workspace tabs​

Each domain exposes seven subtabs accessible through the breadcrumb chips or query-string (?tab=):

  1. Overview - (No domain selected) shows the table described above.
  2. Access - Displays delivery details:
    • CDN access hostname (e.g., example.com.cdn.local).
    • Current TTL and replica count.
    • Assigned edge nodes with copy buttons for IPv4/IPv6.
    • Copy buttons rely on browser clipboard access; allow the permission prompt if copying fails.
    • Refresh button to re-fetch assignments.
    • Helpful messaging when CNAME is disabled or the domain is missing.
  3. Origin - Configure upstream pools:
    • Add, edit, or remove origins with per-origin scheme, host, port, and weight.
    • Use the pencil icon to edit inline; the trash icon removes entries.
    • Click Save changes to persist. Success/failure badge appears beside the button.
    • Metrics cards summarize total origins, TLS coverage, and weight budget.
  4. Rule - Manage caching and purges:
    • Toggles for global cache enable and slice downloads.
    • Rule cards with path regex, TTL, HTTP methods, slice flag, and drag handles.
    • Add rule button duplicates the editable block.
    • Quick purge form at the bottom publishes a cache invalidation for a specific path (requires leading slash; the form will warn if missing).
  5. Header - Set custom upstream request headers:
    • Add headers, edit key/value pairs, or delete rows.
    • Validation warns about empty fields before saving.
  6. Certificate - Handle TLS:
    • Toggle ACME automation on/off. Enabling reveals the _acme-challenge record and the target CNAME returned by acme-dns.
    • Status badge indicates queued, running, issued, failed, etc.
    • Request certificate queues a new ACME run when automation is enabled.
    • Manual upload area accepts PEM fullchain and private key (standard copy-paste). Uploading clears the form on success.
  7. Delete - Safely remove the domain:
    • Review impact list.
    • Re-type the domain name to unlock the Delete button.
    • Final confirmation dialog ensures the action is intentional.

Pro tip: Whenever you edit origins, cache rules, headers, or certificates, wait for the success toast before navigating away. Navigation cancels unsaved drafts.

3. Service Operations​

Purging cached content​

  • Navigate to Sites -> {Domain} -> Rule tab.
  • In the Quick purge area, enter the path (e.g., /images/logo.png; wildcard patterns such as /assets/* only work if your edge purge policy supports them).
  • Click Purge now. The UI displays success/failure in a toast.
  • Purges are broadcast to the edge immediately; allow a few seconds for nodes to invalidate content.

Watching ACME progress​

  • Stay on the Certificate tab during issuance.
  • Status badge updates every 1.5 seconds while automation is active.
  • Use the copy buttons to bring DNS targets into your registrar UI when enabling automation.

Inspecting access footprint​

  • Use the Access tab to confirm which edge POPs currently serve a domain.
  • Refresh if you recently edited node definitions or expect different replicas.

4. Monitoring & Health​

Platform status panel​

Located in the right rail:

  • Control plane badge shows whether API + Redis are healthy. Hover for error details if degraded.
  • Edges displays total nodes, counts of up/down, and the timestamp of the last check.
  • Click Refresh (circular arrow) in relevant cards to re-fetch data.

Status console (Grafana)​

  • Click Status Console in the header. The dashboard opens in a new tab using the configured Grafana URL.
  • Use Grafana to review edge metrics, cache hit ratios, request latency, and alarms.

Prometheus & alerts (read-only)​

  • Prometheus and alerting integrations are pre-wired in deployments. End users typically consume these through Grafana panels; contact operations if you need direct Prometheus access or alert subscriptions.

5. Account & Team Management​

Users page​

  • Lists every control-plane user with email, status (Active/Inactive), and last log-in.
  • Actions:
    • Add user dialog collects username, email, password, and status.
    • Edit (pencil) opens a dialog to adjust email or status.
    • Delete (trash) prompts for confirmation before removing the account.
    • Status switch within the form quickly activates/deactivates access.

Disable accounts instead of deleting them if you expect to reinstate access later.

Tokens page​

Used to manage API/service tokens that automate Cirrus tasks.

Workflow:

  1. Enter the master token (provided by your administrator) in the top card.
  2. Click Save; the token is stored in your browser's localStorage and used for subsequent API calls.
  3. The tokens table lists existing service tokens (label, creation time, last use, masked suffix).
  4. Create token opens a dialog--enter a label and confirm. The UI shows the full secret once; copy it immediately via the copy button.
  5. Use the trash icon to revoke tokens you no longer need.

Persistent warnings are displayed if no master token is saved, helping you avoid accidental unauthenticated calls.

Personal settings​

  • Visit Settings to change your password.
  • The form provides live strength feedback (length, upper/lower case, number, special character requirements).
  • On success, the app logs you out, clearing browser storage for security. Sign back in with the new password.

Logging out​

  • Open the profile dropdown (top-right avatar) and choose Log out. The session cookie is cleared and you are redirected to /login.

6. Accessibility & Productivity Shortcuts​

  • Table rows are keyboard navigable; press Enter or Space while focused to open the domain detail view.
  • Copy buttons carry accessible labels for screen readers (Copy IPv4, Copy target, etc.).
  • Buttons and toggles include explicit text labels alongside icons to assist color-blind users.
  • Theme toggle honors system preferences out of the box.

7. Troubleshooting (End-User Focus)​

ProblemSuggested Action
Cannot sign inDouble-check credentials. If the error persists, ask an admin to reset your password or reactivate the account.
Site missing from listRefresh the Sites page. If still missing, confirm with your team that the domain was created.
Access tab shows error 405 (CNAME disabled)DNS publishing is turned off. Contact operations to enable the CNAME service.
Origin changes not taking effectEnsure you clicked Save changes (green success badge). If origins revert after refresh, verify your permissions or check for concurrent edits.
Cache purge reports success but content persistsAllow up to 30 seconds for propagation. Confirm you purged the correct path and that the domain's cache is enabled.
ACME status stuck at queued/failedConfirm the _acme-challenge CNAME points to the target shown in the UI. Check Celery/worker logs or alert operations if the issue continues.
Service token creation failsEnsure the master token saved in the top card is correct. You can re-enter/update it at any time.
Password change succeeds but I'm logged outThis is expected. Sign in again with the new password.

8. Quick Reference​

TaskLocationNotes
Add a domainSites -> Add SiteRequires origin details.
View assigned edge nodesSites -> {Domain} -> AccessUse copy buttons for IPs.
Update origin poolSites -> {Domain} -> OriginRemember to save.
Adjust cache rules / purgeSites -> {Domain} -> RuleWildcards depend on edge purge support.
Upload TLS cert / trigger ACMESites -> {Domain} -> CertificateACME toggle adds DNS instructions.
Remove a domainSites -> {Domain} -> DeleteRequires typing the domain.
Check platform healthRight rail status cardsClick Refresh for latest info.
Open GrafanaHeader -> Status ConsolePops a new tab.
Add/disable userUsers tabOnly visible to admins.
Manage API tokensTokens tabMaster token stored locally.
Change your passwordSettings tabLogs you out after success.

For deployment-specific procedures or infrastructure details, refer to your organization's internal runbooks. This manual covers everything you can accomplish from the Cirrus CDN frontend. If a feature seems missing or misbehaving, raise a ticket with operations or consult the technical documentation in docs/technical.md for deeper context.