Skip to content

Sysadmin Onboarding

Use this page when you install, take over, or troubleshoot a BucketReef deployment. It is a routing page: keep it open while you jump to the detailed runbooks.

First 30 minutes

  1. Identify the deployment target and image tag policy. Start with Docker Compose for a local or single-host stack, or Helm for Kubernetes. Keep the image tag, chart values, Compose .env, and release notes. The local quickstart builds its checkout; the Helm defaults deliberately remain on the stable release and require paired backend/frontend overrides to validate unpublished code.

  2. Confirm the runtime contract. Use Configuration to locate the database, secrets, CORS, TLS, and scheduler token settings. Keep secret locations, DATABASE_URL, trusted UI origin, and INTERNAL_CRON_TOKEN.

  3. Create and secure the first administrator. Issue a temporary web URL with python -m app.scripts.issue_first_admin_bootstrap, or use create_first_admin as a direct CLI fallback. Complete passkey enrollment before treating the installation as ready. Keep no bootstrap URL in tickets, logs, shell history exports, or shared notes.

  4. Optionally configure the first storage endpoint. Check the Backends matrix and Ceph RGW notes before promising a feature. Keep the endpoint URL, provider type, feature flags, and healthcheck mode.

  5. Verify health, scheduler, and day-2 jobs. Use Healthchecks and Observability before inviting users. Keep the latest healthcheck, CronJob or scheduler status, and backend log location.

  6. Decide which product surfaces are enabled. Use Configuration and Production readiness to record feature flags, role/group mapping, and account links for the first rollout.

  7. Protect the database, credential key, and deployment values. Use Backup and restore and Security. Keep the backup schedule, restore-test result, and credential-key owner.

  8. Run a storage handover with the intended admin profile when storage is in scope. Follow the Storage admin runbook and keep the first endpoint, account/context, bucket/object validation, and audit evidence.

Find the right page fast

I need to... Start here Then check
Evaluate locally from nothing Local quickstart Authentication security, Configuration
Deploy a manual lab or single-host environment Deploy with Docker Compose Configuration, Production readiness
Deploy on Kubernetes Deploy with Helm Backup and restore, Security
Make the deployment safe for real users Production readiness Security, Observability
Know which environment variable or setting controls a behavior Configuration Feature availability
Debug missing menus, stale metrics, or failed jobs Observability Healthchecks, Quota monitoring, Billing
Restore after a host, pod, or database issue Backup and restore Production readiness
Prepare an upgrade Upgrade and compatibility Backup and restore, Production readiness
Check whether a backend supports a feature Backends compatibility matrix Ceph RGW, Other S3 implementations

Triage from a user report

User report Check first Useful evidence
A workspace, menu, or action is missing Feature flag, role, account link, Manager tool access, endpoint capability. User email, workspace, intended account/context, screenshot.
AccessDenied appears during an S3 action Storage-side IAM/S3 policy and selected execution identity. Bucket/key, context selector, route, upstream error id if present.
Health, quota, billing, or usage data is stale Scheduler/CronJob status, INTERNAL_CRON_TOKEN, latest collection logs. Job schedule, last successful run, backend log excerpt.
Portal or Browser cannot open files Browser sub-flags, Portal account link, Storage Space grants, endpoint capability. Workspace, Storage Space or bucket, role/grant, exact action.
An object or bulk data operation failed Provider S3 access logs, backend route logs, upstream S3/RGW response. Personal executor identity, bucket/key, operation id, target prefix.
A purge, migration, global restore, or history cleanup failed Application audit and backend route logs. Actor, account/context, workflow id, target scope.

What an operator should keep in hand

  • Deployment method, image tags, chart values or Compose .env ownership.
  • Database location, backup schedule, and last restore-test result.
  • Credential encryption key owner and recovery location.
  • Secret manager paths for JWT, refresh, scheduler, SMTP, LDAP/OIDC, and storage credentials.
  • Feature-flag decisions for Admin, Manager, Portal, Browser, Ceph Admin, Storage Ops, billing, endpoint status, quota, and usage history.
  • First storage endpoint capability notes and healthcheck mode.
  • Support handover links: Storage admin runbook, User troubleshooting, and Observability.

Boundaries to remember

  • Admin governs users, endpoints, settings, audit, and platform state. It does not grant storage permission by itself.
  • Manager and Browser execute native S3/IAM actions with the selected account, connection, S3 user, or Ceph Admin context.
  • Portal uses database Storage Space metadata and grants, then projects storage-side policies where external access keys need enforcement.
  • Ceph Admin is cluster-level RGW administration and should stay separate from tenant-scoped Manager workflows.