Deploying Jauth

Introduction

Jauth is an installable standalone user authorization service that provides authentication capabilities for your applications. Supporting JWT (JSON Web Tokens) and third-party OAuth providers like Google, Facebook, and Apple, Jauth enables you to add secure user authentication without building it from scratch.

Built as a lightweight, containerized service, Jauth handles user registration, login, token management, and social authentication. The service exposes a REST API that your applications can integrate with to authenticate users and validate sessions.

Key highlights of Jauth:

• JWT Authentication: Issue and validate JSON Web Tokens
• Third-Party OAuth: Support for Google, Facebook, and Apple login
• User Management: Registration, login, and account management
• Token Refresh: Secure token refresh mechanisms
• Event Callbacks: Webhook notifications for auth events
• MySQL Backend: Reliable data persistence
• REST API: Clean API for integration
• Lightweight: Minimal resource footprint
• Docker Ready: Easy containerized deployment
• Open Source: MIT licensed

This guide walks through deploying Jauth on Klutch.sh using Docker, configuring OAuth providers, and integrating authentication into your applications.

Why Deploy Jauth on Klutch.sh

Deploying Jauth on Klutch.sh provides several advantages for authentication services:

Simplified Deployment: Klutch.sh automatically builds and deploys your Jauth container from a Dockerfile.

Persistent Storage: Attach persistent volumes for your MySQL database to maintain user data.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for secure authentication.

GitHub Integration: Connect your configuration repository for automated deployments.

Scalable Resources: Allocate CPU and memory based on expected authentication traffic.

Environment Variable Management: Securely store secrets, API keys, and OAuth credentials.

Custom Domains: Use your domain for the authentication endpoint.

Always-On Availability: Your auth service remains accessible 24/7.

Prerequisites

Before deploying Jauth on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Jauth configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) OAuth credentials from Google, Facebook, or Apple
• (Optional) A custom domain for your Jauth instance

Understanding Jauth Architecture

Jauth operates as a standalone microservice:

API Server: Handles authentication requests, token issuance, and validation.

MySQL Database: Stores user accounts, tokens, and session data.

OAuth Integration: Communicates with third-party identity providers.

Event System: Dispatches webhooks for authentication events.

Preparing Your Repository

Repository Structure

jauth-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

FROM pjongy/jauth:latest

# Environment variables configured via Klutch.sh
ENV JWT_SECRET=${JWT_SECRET}
ENV MYSQL_HOST=${MYSQL_HOST}
ENV MYSQL_USER=${MYSQL_USER}
ENV MYSQL_PASSWORD=${MYSQL_PASSWORD}
ENV MYSQL_DATABASE=${MYSQL_DATABASE}

# Expose the API port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
JWT_SECRET	Yes	-	Secret key for JWT signing
MYSQL_HOST	Yes	-	MySQL database host
MYSQL_USER	Yes	-	MySQL username
MYSQL_PASSWORD	Yes	-	MySQL password
MYSQL_DATABASE	Yes	-	MySQL database name
INTERNAL_API_KEY	No	-	Key for internal API access
EVENT_CALLBACK_URL	No	-	URL for event webhooks
WORKER_COUNT	No	4	Number of worker processes
GOOGLE_CLIENT_ID	No	-	Google OAuth client ID
GOOGLE_CLIENT_SECRET	No	-	Google OAuth client secret
FACEBOOK_APP_ID	No	-	Facebook OAuth app ID
FACEBOOK_APP_SECRET	No	-	Facebook OAuth app secret

Deploying Jauth on Klutch.sh

Generate a JWT Secret

Generate a secure secret for JWT signing:

openssl rand -hex 64

Save this secret securely.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Jauth deployment configuration"
git remote add origin https://github.com/yourusername/jauth-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “jauth” or “auth-service”.

Deploy MySQL First

Deploy a MySQL instance on Klutch.sh. Note the connection details.

Create a New App for Jauth

Within your project, create a new app:

1. Connect your GitHub repository
2. Select the repository containing your Dockerfile
3. Configure HTTP traffic on port 8080

Set Environment Variables

Configure the required environment variables:

Variable	Value
JWT_SECRET	Your generated JWT secret
MYSQL_HOST	Your MySQL host address
MYSQL_USER	Your database username
MYSQL_PASSWORD	Your database password
MYSQL_DATABASE	jauth

For OAuth providers (optional):

Variable	Value
GOOGLE_CLIENT_ID	Your Google OAuth client ID
GOOGLE_CLIENT_SECRET	Your Google OAuth client secret
FACEBOOK_APP_ID	Your Facebook app ID
FACEBOOK_APP_SECRET	Your Facebook app secret

Deploy Your Application

Click Deploy to start the build process.

Access Jauth

Once deployment completes, your Jauth API is available at https://your-app-name.klutch.sh.

API Integration

User Registration

Register a new user:

curl -X POST https://your-app.klutch.sh/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword"
  }'

User Login

Authenticate and receive tokens:

curl -X POST https://your-app.klutch.sh/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Token Refresh

Refresh an expired access token:

curl -X POST https://your-app.klutch.sh/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
  }'

Token Validation

Validate a token:

curl -X POST https://your-app.klutch.sh/api/v1/auth/validate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

OAuth Integration

Google Login

Configure Google OAuth:

1. Create OAuth credentials in Google Cloud Console
2. Set authorized redirect URI to https://your-app.klutch.sh/api/v1/auth/google/callback
3. Add client ID and secret to environment variables

Initiate Google login:

window.location.href = 'https://your-app.klutch.sh/api/v1/auth/google';

Facebook Login

Configure Facebook OAuth:

1. Create a Facebook App in the Developer Console
2. Set valid OAuth redirect URI
3. Add app ID and secret to environment variables

Apple Login

Configure Apple Sign-In:

1. Register in Apple Developer Portal
2. Create a Service ID for Sign in with Apple
3. Configure credentials in environment variables

Event Webhooks

Configuring Webhooks

Set the callback URL via environment variable:

EVENT_CALLBACK_URL=https://your-app.com/auth-events

Event Types

Jauth can notify your application about:

• User registration
• User login
• Token refresh
• Password reset
• Account deletion

Webhook Payload

{
  "event": "user.login",
  "timestamp": "2026-02-06T12:00:00Z",
  "user_id": "12345",
  "data": {
    "email": "user@example.com",
    "method": "password"
  }
}

Production Best Practices

Security Recommendations

• JWT Secret: Use a strong, randomly generated secret (64+ characters)
• HTTPS Only: Ensure all traffic uses HTTPS
• Token Expiry: Set appropriate token expiration times
• Password Policy: Enforce strong password requirements
• Rate Limiting: Implement rate limiting on auth endpoints
• Database Security: Use strong MySQL credentials

Token Management

• Short-lived Access Tokens: 15-60 minutes recommended
• Longer Refresh Tokens: Days to weeks, stored securely
• Token Rotation: Rotate refresh tokens on use
• Secure Storage: Store tokens securely on client side

Backup Strategy

1. Database Backups: Regular MySQL backups
2. Secret Backup: Securely store JWT secret
3. OAuth Credentials: Document OAuth provider settings

Troubleshooting Common Issues

Authentication Failures

Symptoms: Users can’t log in.

Solutions:

• Verify database connectivity
• Check password hashing compatibility
• Review JWT secret configuration
• Check for rate limiting

Token Issues

Symptoms: Tokens rejected as invalid.

Solutions:

• Verify JWT_SECRET matches between token creation and validation
• Check token expiration
• Ensure correct token type (access vs refresh)

OAuth Not Working

Symptoms: Third-party login fails.

Solutions:

• Verify OAuth credentials are correct
• Check redirect URI configuration
• Review OAuth provider console for errors
• Ensure HTTPS is working properly

Additional Resources

• Jauth GitHub Repository
• JWT.io - JWT Debugger
• Google Identity Platform
• Facebook Login Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Jauth on Klutch.sh provides a standalone authentication service with JWT support and third-party OAuth integration. The combination of Jauth’s lightweight design and Klutch.sh’s container hosting enables rapid deployment of secure authentication for your applications.

Whether you’re building a new application that needs user authentication or adding social login to an existing project, Jauth on Klutch.sh delivers the infrastructure needed for secure, scalable authentication services.