Skip to content
Klutch.sh Docs

Deploying a 2FAuth App

Introduction

2FAuth is an open-source two-factor authentication manager with a web UI. This guide shows how to containerize 2FAuth with a Dockerfile, connect it to PostgreSQL or MySQL, persist encrypted secrets, and deploy it to Klutch.sh over HTTP.

Prerequisites

  • GitHub repository containing your Dockerfile.
  • PostgreSQL or MySQL database (managed or deployed separately).
  • Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM 2fauth/2fauth:latest


# Default port
ENV PORT=8000
EXPOSE 8000

Required environment variables

  • APP_URL – public URL, e.g., https://example-app.klutch.sh
  • APP_KEY – strong secret key (php artisan key:generate value)
  • DB_CONNECTION – pgsql or mysql
  • DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
  • PORT=8000

Optional environment variables

  • LOG_CHANNEL=single
  • APP_DEBUG=false
  • MAIL_MAILER and SMTP settings if you enable email
  • SESSION_LIFETIME to adjust session duration

Persistence

2FAuth stores data in the database. To keep local storage for sessions/cache, attach a volume:

  • Mount path: /var/www/html/storage
  • Size: minimal; primarily for cache and compiled assets

Networking

  • Protocol: HTTP
  • Internal port: 8000
  • Users reach https://example-app.klutch.sh while Klutch.sh routes to port 8000 inside the container.
Terminal window
curl -I http://localhost:8000

Deployment on Klutch.sh

  1. Push your Dockerfile to GitHub.
  2. In klutch.sh/app, create a new app and select GitHub as the source.
  3. Klutch.sh automatically detects the Dockerfile in the repository root.
  4. Select HTTP traffic and set the internal port to 8000.
  5. Add environment variables for APP_URL, APP_KEY, database connection, and any mail or debug settings. Mark secrets as sensitive.
  6. Attach a persistent volume at /var/www/html/storage if you need to persist cache/session storage.
  7. Deploy. After the app starts, create your admin account and begin adding 2FA secrets.

Verification

  • UI: open https://example-app.klutch.sh and confirm the login/signup page loads.

  • Quick check:

    Terminal window
    curl -I https://example-app.klutch.sh

Next steps

  • Enforce HTTPS at the edge and rotate the APP_KEY only during re-installs.
  • Configure database backups and, if used, storage volume snapshots.
  • Set up email for account recovery and notifications.