Overview

This guide covers deploying Guardian in both local development and production environments, including database setup, environment configuration, and running the service.

Local Development

For local development, Guardian provides a Docker Compose setup that configures MySQL, Redis, and runs database migrations.

For step-by-step local setup instructions, refer to the Quick Start Guide.

Production Deployment

Infrastructure Requirements

Before deploying Guardian, ensure you have:

• MySQL Database 8.0+: For storing Guardian data : Download
• Redis Cache 6.2+: For temporary state management :Download
• Compute Environment:Capable of running Java 17 JDK version:Download

Database Setup

Use any external or managed MySQL instance and create:

CREATE DATABASE guardian;
CREATE USER 'guardian'@'%' IDENTIFIED BY 'secure_password_here';
GRANT ALL PRIVILEGES ON guardian.* TO 'guardian'@'%';
FLUSH PRIVILEGES;

These values will be referenced in .env file.

Redis Setup

Guardian requires Redis 6.2+ (standalone or cluster mode).

Note: Set GUARDIAN_REDIS_TYPE=STANDALONE or GUARDIAN_REDIS_TYPE=CLUSTER accordingly in .env file

Configuration

Step 1: Create Directories

Create directories where Guardian will run and store its configuration, logs, and application files.

mkdir -p /opt/guardian/logback
mkdir -p /var/logs

Step 2: Download Guardian Files

Download the following from releases:

• guardian.jar - Application JAR
• logback.xml - Logging configuration

Set up the following structure:

/opt/guardian/
  ├─ guardian.jar
  ├─ logback/
  │   └─ logback.xml
  └─ .env

Step 3: Create .env File

Create a .env file with the following configuration:

# Database Configuration
GUARDIAN_MYSQL_WRITER_HOST=<your-db-host.example.com>
GUARDIAN_MYSQL_READER_HOST=<your-db-host.example.com>  # Can be same as writer if no read replica
GUARDIAN_MYSQL_DATABASE=guardian
GUARDIAN_MYSQL_USER=<db-user>
GUARDIAN_MYSQL_PASSWORD=<db-password>
GUARDIAN_MYSQL_WRITER_MAX_POOL_SIZE=10
GUARDIAN_MYSQL_READER_MAX_POOL_SIZE=40

# Redis Configuration
GUARDIAN_REDIS_HOST=<your-redis-host.example.com> # Use CLUSTER endpoint for Cluster mode
GUARDIAN_REDIS_PORT=6379
GUARDIAN_REDIS_TYPE=STANDALONE  # Use CLUSTER for Redis cluster mode

# Application Configuration
GUARDIAN_PORT=8080

# HTTP Client Configuration (optional, defaults shown)
GUARDIAN_HTTP_CONNECT_TIMEOUT=1000
GUARDIAN_HTTP_READ_TIMEOUT=1000
GUARDIAN_HTTP_WRITE_TIMEOUT=1000
GUARDIAN_TENANT_CONFIG_REFRESH_INTERVAL=10

Note: Store sensitive values in a secrets manager or protected files with restricted permissions

chmod 600 /opt/guardian/.env

Ensure the machine can reach DB and Redis before running migrations.

Database Migrations

Guardian uses Liquibase for database schema management. Migrations are located in src/main/resources/migrations/.

Note: Run migrations manually on your database before starting Guardian. This is the recommended and safest approach for production.

Running through Liquibase

1. Install Liquibase (if not installed): Download
2. Run this from any machine or any host with database access:

   liquibase \
     --url="jdbc:mysql://your-db-host.example.com:3306/guardian" \
     --username=<db-user> \
     --password=<db-password> \
     --changeLogFile=src/main/resources/migrations/changelog.xml \
     update

3. Verify the schema:

   mysql -h <your-db-host.example.com> -u <db-user> -p guardian -e "SHOW TABLES;"

   You should see tables like tenant, client, scope, etc.

Running the Application

Create Guardian User

Create a dedicated system user for running the Guardian service:

sudo useradd -r -s /bin/false guardian
sudo chown -R guardian:guardian /opt/guardian
sudo chown -R guardian:guardian /var/logs

Run as a Service (Systemd or Equivalent)

Create service file /etc/systemd/system/guardian.service:

[Unit]
Description=Guardian Authentication Service
After=network.target

[Service]
Type=simple
User=guardian
Group=guardian
WorkingDirectory=/opt/guardian
EnvironmentFile=/opt/guardian/.env
ExecStart=/usr/bin/java -Dlogback.configurationFile=/opt/guardian/logback/logback.xml -jar /opt/guardian/guardian.jar
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=guardian

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable guardian
sudo systemctl start guardian
sudo systemctl status guardian

Direct Java Execution

Useful for testing or simple setups.

cd /opt/guardian
source .env
java -Dlogback.configurationFile=logback/logback.xml -jar guardian.jar

Verification

1. Health check:

curl http://localhost:8080/healthcheck

2. Test authentication flow:

curl --location 'http://localhost:8080/v2/passwordless/init' \
  --header 'Content-Type: application/json' \
  --header 'tenant-id: tenant1' \
  --data '{
    "client_id": "client1",
    "scopes": ["default"],
    "flow": "signinup",
    "response_type": "token",
    "contacts": [{
      "channel": "sms",
      "identifier": "9999999999"
    }]
  }'

Environment Variables Reference

For a complete list of environment variables and configuration options, refer to the Guardian Configuration.

Troubleshooting

Check Logs

# Application logs (requests, auth flows, errors)
tail -f /var/logs/guardian.log

# Service logs - if using Systemd (startup issues, JVM errors, crashes)
sudo journalctl -u guardian -n 100

Note: Application log location is configured in logback.xml. (Default: /var/logs/guardian.log)

If the issue isn’t clear, continue with the checks below.

Common Issues and Fixes

1. Database connection failure
   • Verify GUARDIAN_MYSQL_WRITER_HOST and GUARDIAN_MYSQL_READER_HOST are correct
   • Test connection: mysql -h <HOST> -u <USER> -p
   • Check firewall/security group rules
   • Verify credentials
2. Redis connection failure
   • Verify GUARDIAN_REDIS_HOST is correct
   • Test connection: redis-cli -h <HOST> ping
   • Verify GUARDIAN_REDIS_TYPE matches your setup
3. Port already in use
   • Check if port 8080 is available: netstat -tuln | grep 8080 or ss -tuln | grep 8080
   • Change GUARDIAN_PORT if needed
4. JAR file not found
   • Verify file exists: ls -la /opt/guardian/guardian.jar
   • Check file permissions: ls -l /opt/guardian/guardian.jar
   • Fix ownership if needed: sudo chown guardian:guardian /opt/guardian/guardian.jar