docs / admin / admin-basics.md

Administration

This section covers day-to-day and operational administration of a self-hosted entrytwo instance.

Users, Roles, and Access

entrytwo has three roles:

ADMIN: Full access. Can manage users, invitations, periods, tax rates, settings, updates, backups, bank feeds, and AI configuration. Can also do all accountant work.
ACCOUNTANT: Can do normal accounting work (journal entries, reconciliation, invoices, claims, contacts, etc.). Cannot manage users or system settings.
VIEWER: Read-only access to the books.

First Admin (Bootstrap)

On a fresh installation, the very first user created becomes an ADMIN. This is handled via the sign-in page or Admin panel when no admin exists yet.

After the first admin exists, normal user creation and invitations are used.

See:

docs/getting-started/first-steps.md
docs/getting-started/installation.md (bootstrap section)

Creating and Managing Users

Go to Admin → Users.

From there you can:

Create new users (in development this may use direct creation; in production usually via invitation links).
Assign or change roles (ADMIN / ACCOUNTANT / VIEWER).
Disable users.
There are safety checks: you cannot remove or demote the last remaining ADMIN.

Invitations

Admins can generate invitation links for new users (Admin → Users). The plain token / invite URL is shown when created (and emailed when SMTP is configured).

Invitations carry a role (ADMIN, ACCOUNTANT, or VIEWER) and an expiry.

The invitee must sign in with exactly the invited email (case-insensitive) via Google, Microsoft, or magic link. A different OAuth account is denied and does not create a user.

Authentication Options

Magic link via SMTP (branded email, single-use, 30 minutes). Prior unused links for the same address are invalidated when a new one is sent.
OAuth: Google and/or Microsoft Entra ID when client ID + secret are set. Redirect URIs: {AUTH_URL}/api/auth/callback/google and .../microsoft-entra-id.
Development instant email sign-in (/api/auth/dev) — only when NODE_ENV !== production. Not available on a real VPS production deploy.
After bootstrap, new users need an active invitation. Existing users can sign in without a new invite.
Sign out: settings (gear) menu in the top bar.

2FA (TOTP) is supported. In production, ADMIN users must complete TOTP setup before using the app. Recovery codes are one-time use.

Production checklist (HTTPS, AUTH_URL, AUTH_TRUST_HOST, health auth.productionReady): see the app repo docs/VPS-Auth-Install.md.

Accounting Periods

Admin → Periods

You can open and close accounting periods. Closing a period is a signal that the books for that time are finalized (useful for reporting, tax, and audit comfort).

The Git model still allows you to look at history inside a closed period, and you can always create correcting entries on a branch or via rollback + new commits.

Bank Feeds and Processor Integration

Admin → Bank Feeds

Supported live processor feeds include Stripe (and PayPal in some configurations).

Connect a feed by providing credentials (stored encrypted with ENCRYPTION_KEY).
Sync transactions.
High-confidence payouts/charges can optionally create simple journal entries (often disabled by default to respect the chat lock).

For other banks and cards, the primary path is uploading statements or transaction tables through chat (PDF or pasted data).

See also the AI workflow in docs/ai/using-the-ai.md.

Tax Configuration

Admin → Tax

Define tax rates for your jurisdictions (e.g. DE 19%/7%, AT 20%, US-CA 8.25%, etc.).

These rates are used when creating journal entries, invoices, and claims.

Default jurisdiction can be set in company settings.

Company Settings

Admin → Company (or via onboarding/bootstrap)

Company name
Base currency
Address / jurisdiction
Other preferences

These affect reports, FX handling, and invoice output.

Backup & Restore (Portable Full-System Backups)

entrytwo provides a portable full backup format (.etbackup).

Location: Admin → Backup

What a backup contains

Every database table (journal entries, contacts, users, settings, events, branches, tags, etc.)
Uploaded file assets (receipts, statements, invoice PDFs)
Manifest with SHA-256 checksums and row counts for integrity verification

Key properties

Restore is a complete replacement of the target instance's data.
Intended for disaster recovery or migration to a fresh installation.
The destination instance must use the same ENCRYPTION_KEY that was active when the backup was created (otherwise encrypted bank credentials and similar data cannot be decrypted).
The manifest is validated before restore.

How to use

Go to Admin → Backup.
Export a full backup (or trigger via background job).
Download the .etbackup file and store it securely off-host.
On a new or replacement instance with the correct ENCRYPTION_KEY:
- Go to the import/restore flow and upload the archive.
- The system validates checksums and row counts, then restores.

Additional notes

For pure database-level backup you can still use pg_dump / psql, but you will lose the linked file assets and the convenient manifest checks.
Updates automatically create a pre-update full backup (see Updates section).
See also entrytwo_v1/docs/ENCRYPTION-KEY-ROTATION.md if you ever need to change the encryption key.

Self-Hosted Updates

entrytwo uses a secure, per-customer update delivery system.

High-level flow:

Releases are built as Docker images and signed with cosign (keyless or pinned public key).
A signed manifest describes the latest available version.
The app (or an isolated updater sidecar) pulls the exact digest, verifies the signature, creates a full pre-update backup, runs migrations, performs a health check, and can automatically roll back on failure.
The running app is never disabled just because maintenance lapsed. It simply stops receiving new versions.

See the deep technical document:

entrytwo_v1/docs/Self-Hosted-Update-Delivery.md

In the UI:

Admin → Update shows current status, available update, and lets you trigger an update.
A full backup is created automatically before applying.
Progress and rollback information are shown.

Commercial model reminder (see Licensing section below):

Perpetual license = you own the version you have forever.
Annual maintenance = entitlement to new versions + support.

Licensing and Trial

entrytwo uses a 30-day trial + perpetual license model.

Trial

Starts on first use of a fresh instance (firstUseAt).
Full functionality for 30 calendar days.
A visible trial indicator is shown.
After 30 days without a valid paid license: a blocking paywall appears for normal operation.

License Activation ("verify once, trust forever")

You purchase a license (one-time) and receive a signed license key.
You enter the key once in the app.
The app verifies it (signature + optional online confirmation).
On success the key is stored permanently for this deployment.
After that, all status, paywall, and update decisions read only the stored flag. The external verification service is never called again.
The app works fully offline once licensed.

After licensing

The instance is permanently licensed for this deployment.
The running app is never disabled.
New updates are gated by active maintenance (see Self-Hosted Updates).
Lapsed maintenance → you keep running the last version you received.

See the full policy and implementation details:

entrytwo_docs/Licensing-and-Trial.md
Code comments in lib/license.ts, /api/license/activate, etc.