Appearance
First boot and the operator console
Once the app is running, an installation has two kinds of administrator, and they sign in to different places:
| Signs in at | Looks after | |
|---|---|---|
| The instance operator | /super-admin | The installation: the licence, mail, storage, sign-in providers, and every workspace on it |
| A workspace admin | /login, like everyone else | One workspace: its departments, people, groups, labels, working days |
The operator is not a workspace account and cannot be signed in through Google or another provider — on purpose, since the operator is the person who fixes sign-in when it breaks. The operator's session lasts ten minutes.
1. Claim the operator console
Open /super-admin. On a new installation it asks for an email and a password, and whoever submits it first becomes the operator. Do it straight after the first boot.
If you set BOOTSTRAP_TOKEN (see Installing), the form also asks for that value, so someone who merely finds the address first cannot claim it.
2. Install the licence
Settings → Licence. Paste the licence key you were sent and save. Until this is done, every workspace screen shows that the installation has no licence. Details, and what each status means: The licence.
3. Set up mail
Settings → Mail. Crosdesk sends invitations and one-time sign-in codes; nothing else depends on email.
Mail goes out one of two ways, chosen by Provider:
- smtp — your mail server. The default.
- mailtrap — Mailtrap's sending API, over HTTPS. Use it where the host blocks outgoing SMTP: Railway does below its Pro plan, and there every message waits and then fails with a timeout.
| Setting | What to put |
|---|---|
Provider (mail.provider) | smtp or mailtrap. |
| From | The sender people see, e.g. Crosdesk <desk@example.com>. With Mailtrap, an address on a domain you have verified there. |
Mailtrap token (mailtrap.token) | Mailtrap only: an API token with sending access to that domain. Stored encrypted and never shown again. |
| Host, Port | SMTP only: your server. Port 587 is usual. |
| Security | SMTP only: auto suits most servers. |
| User, Password | SMTP only: the account. The password is stored encrypted and never shown again. |
Mailtrap needs only the From address and the token; the SMTP settings are kept but not used, so switching back needs nothing typed again. With no host (SMTP) or no token (Mailtrap), nothing is sent and the log records an error for each message — invitations can still be handed over as links (step 6).
4. Choose where files are stored
Settings → Storage. Attachments and screen recordings are files, kept in one of two places:
- local — a directory on the server,
/app/storageby default. The Compose file mounts a volume there, so files survive upgrades. Right for a single server. - s3 — an S3-compatible bucket: AWS S3, MinIO, Cloudflare R2. Fill in the endpoint (blank for AWS), region, bucket and keys, and set path-style addressing to match your provider — usually on for MinIO, off for AWS and R2. Required when more than one copy of the app runs, since each copy has its own disk.
Files always pass through Crosdesk on their way in and out; no browser is ever given a bucket address. Switching does not move files already stored — those stay where they were written.
Each start, the log says which store is in use and whether it works — for example Storage: local files in /app/storage (writable), or a warning naming what is wrong with a bucket.
5. The rest, when you need it
The other settings have working defaults:
| Group | What it decides |
|---|---|
| Attachments | Largest file (25 MB by default), files per upload, and the largest image in a document (2 MB by default, at most 10 MB) |
| Recordings | How long screen recordings are kept and how long one may be, and which Recorder extensions may upload |
| Sessions | How long a workspace sign-in lasts |
| Security | How many wrong passwords lock an account; whether workspace admins may copy invitation links |
| Video calls | Zoom rooms for meetings — see Video calls |
| Sign in with … | Google, GitHub, GitHub Enterprise Server and OpenID Connect — see Sign-in providers |
Each row says whether it is set here or still the default. Changes take effect on the next request — nothing is cached and nothing needs a restart.
6. Workspaces and their administrators
Create a workspace from Organisations → New organisation: a name, a slug (the short name in addresses), and the first administrator's email. That person is sent an invitation — or use Copy link on the row to send it yourself. From there the workspace admin invites everyone else.
Sign-up is off by default. Turn on Settings → Security → signup.enabled and anybody who can prove an email address may create one workspace of their own from the sign-in page, as its administrator — see Creating a workspace.
One person can belong to several workspaces with one account, and an organisation can be archived and restored from the same list. See Users for what a workspace admin does next.