# Development Setup

## Important: No Sudo Required

This project is designed to run entirely without sudo/root privileges. All development and testing commands should work with regular user permissions.

### Key Points:

1. **Package Installation**: Use `npm install` (never `sudo npm install`)
2. **Test Execution**: All test commands run without sudo
3. **Development Server**: Runs on user ports (5173 by default)
4. **Playwright**: Browsers install to user directories

### If You Encounter Permission Issues:

- **Node/NPM**: Use a node version manager (nvm, fnm) instead of system-wide installation
- **Browsers**: Playwright will install browsers to `~/.cache/ms-playwright`
- **Ports**: Development server uses port 5173+ (above 1024, no privileges needed)

### Environment Configuration:

```bash
# Set custom port if needed (optional)
export PORT=3000

# Run development server
npm run dev

# Run tests (no sudo needed)
npm run test:smoke
```

### Troubleshooting:

If you see permission errors:
1. Check your Node.js installation (should not require sudo)
2. Clear npm cache: `npm cache clean --force`
3. Remove node_modules and reinstall: `rm -rf node_modules && npm install`
4. For Playwright issues: `npx playwright install` (user-level install)

### System Dependencies (One-time setup):

If you see browser dependency errors, you may need to install system dependencies:

```bash
# For Ubuntu/Debian - this is the ONLY case where sudo may be needed
# (for system-level browser dependencies, not the project itself)
sudo npx playwright install-deps

# Alternative approach - manual dependency installation
sudo apt-get install libavif16
```

**Important**: The system dependencies are for browser support only. All project development commands should still run without sudo.

**Never use sudo for any project development or testing commands - only for one-time system dependency installation if needed.**