Your favorite shift management application!
Enabling Authentication on an Existing Instance
This guide explains how to enable authentication on a BetterShift instance that was previously running without it.
Table of Contents
Before You Start
Prerequisites
- BetterShift instance running with
AUTH_ENABLED=false - Existing calendars created without authentication
- Database backup (recommended)
What Happens to Existing Data
When you enable authentication:
| Data Type | Behavior |
|---|---|
| Calendars | Become "orphaned" (no owner) - invisible to regular users |
| Shifts | Preserved with their calendars |
| Presets | Preserved with their calendars |
| Notes | Preserved with their calendars |
| External Syncs | Preserved with their calendars |
Existing data is not deleted - it becomes orphaned and must be assigned to users through the admin panel.
Migration Steps
Step 1: Backup Your Database
Before making any changes, create a backup:
# SQLite database location (default)
cp ./data/sqlite.db ./data/sqlite.db.backup
# Or if using Docker
docker cp bettershift:/app/data/sqlite.db ./sqlite.db.backup
Step 2: Generate Auth Secret
Generate a secure secret for Better Auth:
npx @better-auth/cli secret
Copy the output - you'll need it in the next step.
Step 3: Configure Environment Variables
Update your .env file:
# Enable authentication
AUTH_ENABLED=true
# Set the generated secret
BETTER_AUTH_SECRET=your-generated-secret-here
# Set your application URL
BETTER_AUTH_URL=https://your-domain.com
# Optional: Configure registration
ALLOW_USER_REGISTRATION=true
Guest access (viewing calendars without login) is a live toggle in the admin panel under System Settings, not an environment variable.
Step 4: Restart the Application
# Docker Compose
docker-compose restart
# Or if running directly
npm run build && npm start
Step 5: Create the First User (Superadmin)
- Navigate to your BetterShift URL
- Click "Register" (or use OAuth if configured)
- Create your account
The first registered user automatically becomes superadmin with full administrative access.
Step 6: Assign Orphaned Calendars
After logging in as superadmin:
- Go to
/admin/calendars - Orphaned calendars appear at the top with an "Orphaned" badge
- For each orphaned calendar:
- Click the action menu
- Select "Transfer Ownership"
- Search for and select the appropriate user
- Confirm the transfer
Handling Orphaned Calendars
What Are Orphaned Calendars?
Orphaned calendars have no owner (ownerId = null). This occurs when:
- Calendars existed before auth was enabled
- The owner was deleted
- Database inconsistencies
Visibility
Orphaned calendars are invisible to all regular users, even superadmins using the normal calendar view. They can only be managed through the admin panel at /admin/calendars.
Resolution Options
| Option | When to Use |
|---|---|
| Transfer | Assign to the appropriate user |
| Delete | Remove if no longer needed (superadmin only) |
| Bulk Transfer | Move multiple calendars to one user |
Bulk Transfer Workflow
For instances with many orphaned calendars:
- Go to
/admin/calendars - Filter by "Orphaned Only"
- Select multiple calendars using checkboxes
- Click "Transfer Selected"
- Choose the destination user
- Confirm the bulk transfer
FAQ
What happens to existing calendars?
They become orphaned (no owner) but retain all data. Assign them to users via the admin panel.
Can users still access their old calendars?
No, orphaned calendars are invisible until assigned. Users need to login, then an admin must transfer ownership to them.
What if I want to disable auth again?
Set AUTH_ENABLED=false in your environment. Calendars with owners will still work, but ownership restrictions won't be enforced.
Can I keep some calendars public?
Yes, after assigning an owner:
- Open calendar settings
- Set "Guest Permission" to "Read" or "Write"
- Turn on Guest Access globally in the admin panel under System Settings
How do I add more admins?
- Login as superadmin
- Go to
/admin/users - Find the user
- Click Edit
- Change role to "Admin"
- Save
What if I lose access to the superadmin account?
If you have database access, you can manually update the user role:
UPDATE user SET role = 'superadmin' WHERE email = '[email protected]';
Then restart the application.
Is there a way to auto-assign calendars?
Not currently. Calendars must be manually assigned through the admin panel. For large migrations, consider a database script.
Rollback Procedure
If you need to revert to no-auth mode:
- Set
AUTH_ENABLED=falsein.env - Restart the application
- All calendars become accessible again (ownership ignored when auth disabled)
Note: User accounts and calendar ownership data are preserved in the database for future re-enabling.