authentikate/docs/quick-start/manual-deployment.md

# Manual Deployment

This guide covers manual deployment of AuthentiKate without Docker. This method gives you more control over the server environment but requires more setup steps.

## Prerequisites

- PHP 8.1 or higher with extensions:
  - BCMath
  - Ctype
  - Fileinfo
  - JSON
  - Mbstring
  - OpenSSL
  - PDO
  - Tokenizer
  - XML
  - cURL
  - GD (optional, for image processing)
- Composer (PHP dependency manager)
- Web server (Apache, Nginx, or similar)
- Database server (MySQL 8.0+, PostgreSQL 13+, or SQLite)
- Git (for cloning the repository)

## Installation Steps

### 1. Clone the Repository

```bash
# Clone from the source repository
git clone https://gitgud.foo/thegrind/authentikate.git
cd authentikate

# Or download and extract the latest release
wget https://gitgud.foo/thegrind/authentikate/-/archive/main/authentikate-main.tar.gz
tar -xzf authentikate-main.tar.gz
cd authentikate-main
```

### 2. Install PHP Dependencies

```bash
# Install Composer dependencies
composer install --optimize-autoloader --no-dev

# For development environments, omit --no-dev
composer install --optimize-autoloader
```

### 3. Environment Configuration

```bash
# Copy the example environment file
cp .env.example .env

# Generate application key
php artisan key:generate
```

Edit the `.env` file with your configuration:

```env
# Application Settings
APP_NAME=AuthentiKate
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com
APP_TIMEZONE=UTC

# Database Configuration (choose one)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=authentikate
DB_USERNAME=your-username
DB_PASSWORD=your-password

# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=your-smtp-server.com
MAIL_PORT=587
MAIL_USERNAME=your-email@domain.com
MAIL_PASSWORD=your-email-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@your-domain.com
MAIL_FROM_NAME="AuthentiKate"

# Session Configuration
SESSION_DRIVER=file
SESSION_LIFETIME=120

# Cache Configuration
CACHE_DRIVER=file
```

### 4. Database Setup

Create a database for AuthentiKate:

::: code-group

```sql [MySQL]
CREATE DATABASE authentikate CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'authentikate'@'localhost' IDENTIFIED BY 'your-secure-password';
GRANT ALL PRIVILEGES ON authentikate.* TO 'authentikate'@'localhost';
FLUSH PRIVILEGES;
```

```sql [PostgreSQL]
CREATE DATABASE authentikate;
CREATE USER authentikate WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE authentikate TO authentikate;
```

```bash [SQLite]
# Create SQLite database file
touch database/database.sqlite
```

:::

Run database migrations:

```bash
# Run migrations
php artisan migrate --force

# Seed initial data (if available)
php artisan db:seed --force
```

### 5. Set Directory Permissions

```bash
# Set proper permissions for storage and cache directories
chmod -R 775 storage
chmod -R 775 bootstrap/cache

# Change ownership to web server user (adjust as needed)
chown -R www-data:www-data storage
chown -R www-data:www-data bootstrap/cache

# Create symbolic link for public storage
php artisan storage:link
```

### 6. Optimize for Production

```bash
# Cache configuration
php artisan config:cache

# Cache routes
php artisan route:cache

# Cache views
php artisan view:cache

# Optimize Composer autoloader
composer install --optimize-autoloader --no-dev
```

## Web Server Configuration

### Apache Configuration

Create a virtual host configuration:

```apache
<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /path/to/authentikate/public
    
    <Directory /path/to/authentikate/public>
        AllowOverride All
        Require all granted
    </Directory>
    
    ErrorLog ${APACHE_LOG_DIR}/authentikate_error.log
    CustomLog ${APACHE_LOG_DIR}/authentikate_access.log combined
</VirtualHost>

# SSL Configuration (recommended)
<VirtualHost *:443>
    ServerName your-domain.com
    DocumentRoot /path/to/authentikate/public
    
    SSLEngine on
    SSLCertificateFile /path/to/your/certificate.crt
    SSLCertificateKeyFile /path/to/your/private.key
    
    <Directory /path/to/authentikate/public>
        AllowOverride All
        Require all granted
    </Directory>
    
    ErrorLog ${APACHE_LOG_DIR}/authentikate_ssl_error.log
    CustomLog ${APACHE_LOG_DIR}/authentikate_ssl_access.log combined
</VirtualHost>
```

Enable required Apache modules:

```bash
sudo a2enmod rewrite
sudo a2enmod ssl
sudo systemctl restart apache2
```

### Nginx Configuration

Create an Nginx server block:

```nginx
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    root /path/to/authentikate/public;
    
    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;
    
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
    
    index index.php;
    
    charset utf-8;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }
    
    error_page 404 /index.php;
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    location ~ /\.(?!well-known).* {
        deny all;
    }
}
```

### PHP-FPM Configuration

Optimize PHP-FPM for production:

```ini
; /etc/php/8.1/fpm/pool.d/authentikate.conf
[authentikate]
user = www-data
group = www-data
listen = /var/run/php/php8.1-fpm-authentikate.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35
pm.max_requests = 500

php_admin_value[disable_functions] = exec,passthru,shell_exec,system
php_admin_flag[allow_url_fopen] = off
```

## Process Management

### Systemd Service (Optional)

Create a systemd service for queue workers (if using queues):

```ini
# /etc/systemd/system/authentikate-worker.service
[Unit]
Description=AuthentiKate Queue Worker
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /path/to/authentikate/artisan queue:work --sleep=3 --tries=3 --max-time=3600
WorkingDirectory=/path/to/authentikate

[Install]
WantedBy=multi-user.target
```

Enable and start the service:

```bash
sudo systemctl enable authentikate-worker
sudo systemctl start authentikate-worker
```

### Cron Jobs

Set up Laravel's task scheduler:

```bash
# Add to crontab (crontab -e)
* * * * * cd /path/to/authentikate && php artisan schedule:run >> /dev/null 2>&1
```

## Performance Optimization

### OPcache Configuration

Add to your PHP configuration:

```ini
; php.ini
opcache.enable=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=4000
opcache.revalidate_freq=2
opcache.fast_shutdown=1
```

### Redis Configuration (Optional)

For better performance, use Redis for caching and sessions:

```bash
# Install Redis
sudo apt install redis-server

# Install PHP Redis extension
sudo apt install php8.1-redis
```

Update your `.env` file:

```env
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
```

## Security Considerations

### File Permissions

```bash
# Set restrictive permissions
find /path/to/authentikate -type f -exec chmod 644 {} \;
find /path/to/authentikate -type d -exec chmod 755 {} \;

# Make artisan executable
chmod +x /path/to/authentikate/artisan

# Secure sensitive files
chmod 600 /path/to/authentikate/.env
```

### Environment Security

- Keep `.env` file outside web root or protect it via web server configuration
- Use strong, unique passwords for database and application key
- Enable HTTPS with valid SSL certificates
- Configure proper firewall rules
- Regularly update PHP, web server, and dependencies

## Backup Strategy

### Database Backup

```bash
#!/bin/bash
# backup-database.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups/authentikate"

# MySQL
mysqldump -u authentikate -p authentikate > "$BACKUP_DIR/authentikate_$DATE.sql"

# PostgreSQL
pg_dump -U authentikate authentikate > "$BACKUP_DIR/authentikate_$DATE.sql"

# Compress backup
gzip "$BACKUP_DIR/authentikate_$DATE.sql"
```

### Application Backup

```bash
#!/bin/bash
# backup-app.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backups/authentikate"
APP_DIR="/path/to/authentikate"

# Backup storage directory
tar -czf "$BACKUP_DIR/storage_$DATE.tar.gz" -C "$APP_DIR" storage

# Backup environment file
cp "$APP_DIR/.env" "$BACKUP_DIR/env_$DATE.backup"
```

## Updates and Maintenance

### Application Updates

```bash
# Backup before updating
./backup-database.sh
./backup-app.sh

# Pull latest code
git pull origin main

# Update dependencies
composer install --optimize-autoloader --no-dev

# Run migrations
php artisan migrate --force

# Clear caches
php artisan config:clear
php artisan cache:clear
php artisan view:clear

# Rebuild caches
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

### Log Rotation

Configure log rotation to prevent disk space issues:

```bash
# /etc/logrotate.d/authentikate
/path/to/authentikate/storage/logs/*.log {
    daily
    missingok
    rotate 52
    compress
    notifempty
    create 644 www-data www-data
    copytruncate
}
```

## Troubleshooting

### Common Issues

1. **Permission Denied Errors**
   ```bash
   sudo chown -R www-data:www-data /path/to/authentikate/storage
   sudo chown -R www-data:www-data /path/to/authentikate/bootstrap/cache
   ```

2. **Database Connection Issues**
   - Verify database credentials in `.env`
   - Check database server is running
   - Ensure user has proper permissions

3. **Internal Server Error (500)**
   - Check web server error logs
   - Verify PHP extensions are installed
   - Check Laravel logs in `storage/logs/`

4. **Composer Issues**
   ```bash
   # Clear Composer cache
   composer clear-cache
   
   # Update Composer
   composer self-update
   ```

### Log Files

Monitor these log files for issues:

- Laravel logs: `/path/to/authentikate/storage/logs/laravel.log`
- Web server logs: `/var/log/apache2/` or `/var/log/nginx/`
- PHP-FPM logs: `/var/log/php8.1-fpm.log`
- System logs: `/var/log/syslog`

## Next Steps

After successful deployment:

1. Access your AuthentiKate installation at your configured domain
2. Complete the initial setup wizard
3. Configure your first OIDC clients
4. Set up user authentication providers
5. Review security settings and SSL configuration

For detailed configuration and usage instructions, see the [User Guide](/user-guide/).