nidus/MIGRATION.md

Data Directory Migration Guide

This migration unifies the user data directory structure from a fragmented layout to a consistent nested format.

Before (Old Structure)

data/
├── files/
│   └── alice/              # WebDAV files
│       └── documents/
│           └── file.txt
├── alice/
│   ├── cal-personal/       # CalDAV calendar
│   │   └── event1.ics
│   └── card-contacts/      # CardDAV address book
│       └── contact1.vcf
└── bob/
    ├── cal-work/
    │   └── meeting.ics
    └── card-addressbook/
        └── address.vcf

After (New Unified Structure)

data/
├── alice/
│   ├── files/              # WebDAV files
│   │   └── documents/
│   │       └── file.txt
│   ├── calendars/          # CalDAV calendars
│   │   └── personal/
│   │       └── event1.ics
│   └── addressbooks/       # CardDAV address books
│       └── contacts/
│           └── contact1.vcf
└── bob/
    ├── files/
    ├── calendars/
    │   └── work/
    └── addressbooks/
        └── addressbook/

Migration Details

What Changed

1. WebDAV files: data/files/<username>/ → data/<username>/files/
2. CalDAV calendars: data/<username>/cal-<name>/ → data/<username>/calendars/<name>/
3. CardDAV address books: data/<username>/card-<name>/ → data/<username>/addressbooks/<name>/

Migration Tool

A migration tool is provided that automatically restructures the data directory. It is idempotent and can be run multiple times safely.

Using nidusctl (Recommended)

go run ./tools/nidusctl -config config.yaml migrate

Using standalone migrate tool

go run ./tools/migrate -config config.yaml

Verbose output

go run ./tools/nidusctl -config config.yaml migrate --verbose

What the Migration Does

1. For each user directory in the data directory:

   • Creates <username>/ if it doesn't exist
   • Moves files/<username>/ → <username>/files/ (if exists)
   • Moves cal-<name>/ → <username>/calendars/<name>/
   • Moves card-<name>/ → <username>/addressbooks/<name>/

2. The old files/ directory is left in place (can be manually removed after verification)

Backward Compatibility

The migration is fully backward compatible:

• The migration tool handles both old and new structures
• If files are already in the new location, they are not moved
• Running migration multiple times is safe (idempotent)

Server Integration

The server automatically runs migration on startup (if enabled in config). No manual migration is required for new installations.

Testing

After migration, verify:

# Check data structure
ls -la data/

# Run tests
go test ./...

# Start server to verify WebDAV, CalDAV, CardDAV work correctly
go run ./cmd/server -config config.yaml

Manual Verification

After migration, you should see:

$ ls -la data/alice/
calendars/
addressbooks/
files/

Each calendar should be in data/<user>/calendars/<name>/ format, not cal-<name>/.

Rollback (if needed)

If you need to rollback:

1. Stop the server
2. Restore the data directory from backup
3. Re-run the migration after fixing any issues

Common Issues

Q: Migration reports "directory already exists" warnings A: These are normal if files were already migrated. The migration is idempotent.

Q: Old files/ directory still exists A: This is expected. You can manually remove it after verifying migration success.

Q: Some calendars/address books not visible after migration A: Check the migration logs and verify directory structure. Run find data/ -type d -name "cal-*" to find unmigrated calendars.

Support

If you encounter issues:

1. Check logs for detailed error messages
2. Run migration with --verbose flag
3. Ensure no server processes are running during migration
4. Make backup before migrating in production