Skip to content

Your favorite shift management application!

5.4 KB
Raw Blame

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

  1. Before You Start
  2. Migration Steps
  3. Handling Orphaned Calendars
  4. FAQ

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)

  1. Navigate to your BetterShift URL
  2. Click "Register" (or use OAuth if configured)
  3. Create your account

The first registered user automatically becomes superadmin with full administrative access.

Step 6: Assign Orphaned Calendars

After logging in as superadmin:

  1. Go to /admin/calendars
  2. Orphaned calendars appear at the top with an "Orphaned" badge
  3. 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:

  1. Go to /admin/calendars
  2. Filter by "Orphaned Only"
  3. Select multiple calendars using checkboxes
  4. Click "Transfer Selected"
  5. Choose the destination user
  6. 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:

  1. Open calendar settings
  2. Set "Guest Permission" to "Read" or "Write"
  3. Turn on Guest Access globally in the admin panel under System Settings

How do I add more admins?

  1. Login as superadmin
  2. Go to /admin/users
  3. Find the user
  4. Click Edit
  5. Change role to "Admin"
  6. 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:

  1. Set AUTH_ENABLED=false in .env
  2. Restart the application
  3. 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.