authentikate/docs/guide/first-setup.md

# First Setup

After installing AuthentiKate, you'll want to complete the initial configuration to make it ready for production use.

## Initial Login

When you first start AuthentiKate, it automatically creates an admin user. The credentials are shown in the container logs:

```bash
docker logs authentikate
```

Look for:
```
✅ Initial admin user created:
   Email: admin@authentikate.local
   Password: randomly-generated-password
```

::: tip
Save these credentials securely! You'll need them to access the admin interface.
:::

## Admin Dashboard

After logging in, you'll see the AuthentiKate dashboard with:

- **Applications**: Manage OAuth applications
- **Users**: User management and invitations  
- **Tokens**: View active authentication tokens
- **Profile**: Your user profile settings

## Essential Configuration Steps

### 1. Update Your Profile

1. Click your avatar in the top right
2. Select **"Profile"**
3. Update your information:
   - Change the email from `admin@authentikate.local` to your real email
   - Set a preferred username
   - Upload an avatar (optional)
   - **Change your password** to something secure

### 2. Configure Email (Recommended)

Email is used for:
- User invitations
- Password resets  
- Account verification

Set up email by updating your environment variables:

```yaml
environment:
  MAIL_MAILER: smtp
  MAIL_HOST: smtp.gmail.com
  MAIL_PORT: 587
  MAIL_USERNAME: your-email@gmail.com
  MAIL_PASSWORD: your-app-password
  MAIL_ENCRYPTION: tls
  MAIL_FROM_ADDRESS: auth@yourdomain.com
  MAIL_FROM_NAME: "AuthentiKate"
```

[→ See full email configuration guide](/config/email)

### 3. Set Your Domain

Update the `APP_URL` to match your actual domain:

```yaml
environment:
  APP_URL: https://auth.yourdomain.com
```

This ensures:
- Correct OAuth redirect URLs
- Proper JWT issuer claims
- Working email links

### 4. Create Your First Application

1. Go to **Applications** → **Create Application**
2. Fill in the basic information:
   - **Name**: Your application name (e.g., "Grafana")
   - **Redirect URI**: Where users return after authentication
   - **Icon**: Optional app icon URL

3. Note the generated **Client ID** and **Client Secret**
4. Use these in your application's OAuth configuration

## Security Checklist

Before going to production, verify these security settings:

### ✅ Admin Account
- [ ] Changed default admin email
- [ ] Set a strong, unique password
- [ ] Enabled email verification (if email is configured)

### ✅ Environment
- [ ] Set `APP_ENV=production`
- [ ] Set `APP_DEBUG=false`
- [ ] Using HTTPS with valid SSL certificate
- [ ] `APP_URL` matches your actual domain

### ✅ Database
- [ ] Using persistent volume for data
- [ ] Consider using PostgreSQL/MySQL for production
- [ ] Regular backups configured

### ✅ Reverse Proxy
- [ ] Proper SSL termination
- [ ] Security headers configured
- [ ] Rate limiting in place

## Application Integration

### OIDC Endpoints

Your applications will need these endpoints:

| Endpoint | URL |
|----------|-----|
| Authorization | `https://auth.yourdomain.com/oauth/authorize` |
| Token | `https://auth.yourdomain.com/oauth/token` |
| User Info | `https://auth.yourdomain.com/oauth/userinfo` |
| JWKS | `https://auth.yourdomain.com/.well-known/jwks.json` |
| Discovery | `https://auth.yourdomain.com/.well-known/openid_configuration` |

### OAuth Flow

1. **User clicks login** in your application
2. **Redirect to AuthentiKate** with authorization request
3. **User authenticates** (if not already logged in)
4. **User consents** to application access (if required)
5. **Redirect back** to your application with authorization code
6. **Exchange code** for access token and ID token
7. **Access user info** using the access token

## User Management

### Invitation System

AuthentiKate uses an invitation-based registration system:

1. **Admin creates invitation** with user's email
2. **Invitation email sent** with registration link
3. **User completes registration** using the invitation
4. **User can access applications** they're authorized for

### User Permissions

- **Admin users**: Full access to manage applications and users
- **Regular users**: Can only access authorized applications and manage their own profile

## Backup Strategy

Set up regular backups of your AuthentiKate data:

### SQLite (Default)
```bash
# Daily backup script
#!/bin/bash
docker exec authentikate cp /var/www/html/storage/database/database.sqlite /tmp/backup.sqlite
docker cp authentikate:/tmp/backup.sqlite ./backups/authentikate-$(date +%Y%m%d).sqlite
```

### Full Volume Backup
```bash
# Backup all persistent data
docker run --rm -v authentikate_data:/data -v $(pwd)/backups:/backup alpine tar czf /backup/authentikate-full-$(date +%Y%m%d).tar.gz -C /data .
```

## Common Next Steps

### Popular Integrations
- [Set up Grafana SSO](/integrations/grafana)
- [Configure Nextcloud authentication](/integrations/nextcloud)  
- [Integrate with Traefik forward auth](/integrations/traefik)

### Advanced Configuration
- [Environment variables reference](/config/environment)
- [Database configuration](/config/database)
- [Security settings](/config/security)

### User Management
- [Create user invitations](/guide/invitations)
- [Manage user profiles](/guide/profiles)
- [Handle user permissions](/guide/users)

## Getting Help

If you run into issues:

1. **Check the logs**: `docker logs authentikate`
2. **Verify configuration**: Compare with working examples
3. **Test endpoints**: Use curl or Postman to test OIDC endpoints
4. **Community support**: Check GitHub issues and discussions

Your AuthentiKate instance is now ready for production use! 🎉