Skip to content

README.md

Latest commit

 

History

History
180 lines (123 loc) · 4.13 KB

README.md

File metadata and controls

180 lines (123 loc) · 4.13 KB

FIRM

Passwordless Authentication Server

FIRM is a passwordless authentication server based on draft-feeser-firm-auth-08. It uses Mailgun for inbound email webhooks, Gmail IMAP for small setups, and PostgreSQL for storage. This guide provides bash commands to install and set up FIRM on Linux/amd64 with Go 1.24.2.

Prerequisites

  • Go 1.24.2 linux/amd64
  • PostgreSQL 15 or later
  • Git
  • Mailgun account (for webhooks, configured later)
  • Gmail account (for IMAP fallback, configured later)

Installation

  1. Clone the repo

    git clone https://github.com/alta3/github-actions-the-alta3-way.git
cd ~/github-actions-the-alta3-way

  2. Check your Go version

    go version # Should output go1.24.2 linux/amd64

  3. Install Go (if not installed)

    ./scripts/go_install.sh

  4. Install dependencies

    go mod tidy

Environment Setup

Store secrets (e.g., PostgreSQL credentials) in a .env file, ignored by .gitignore for security. Edit .env with vim to set your credentials.

  1. Create a .env file

    cat <<EOF > .env
PG_USER=postgres
PG_PASSWORD=password
PG_HOST=localhost
PG_PORT=5432
PG_DB=firm
FIRM_USER=firmuser
FIRM_PASSWORD=firmpass
EOF

  2. Edit the .env file

    vim .env

    Edit with your superuser credentials, e.g., PG_USER=roadmatric, PG_PASSWORD=roadmatrix-4d Keep FIRM_USER=firmuser, FIRM_PASSWORD=firmpass or set custom values

  3. Export .env variables

    Make .env variables available to subsequent commands:

    set -a; source .env; set +a
echo Verifing variables:
printenv | grep PG
printenv | grep FIRM

  4. Verify .gitignore

    The repo includes .gitignore with .env to prevent committing secrets. Check it:

    cat .gitignore | grep .env

Database Setup

Set up the firm database with a dedicated user for security. Use exported .env variables to minimize errors. Assumes a PostgreSQL superuser (e.g., roadmatric or postgres) defined in .env.

  1. Install PostgreSQL (if not installed)

    sudo apt update
sudo apt install postgresql postgresql-contrib -y
sudo systemctl start postgresql
sudo systemctl enable postgresql

  2. Create a dedicated user and database

    Create FIRM_USER and PG_DB database using .env variables:

    # Uses PG_USER, PG_PASSWORD, PG_HOST, PG_PORT, FIRM_USER, FIRM_PASSWORD from .env
sudo -u postgres psql <<EOF
CREATE USER $FIRM_USER WITH PASSWORD '$FIRM_PASSWORD';
CREATE DATABASE $PG_DB OWNER $FIRM_USER;
GRANT ALL PRIVILEGES ON DATABASE $PG_DB TO $FIRM_USER;
EOF

if [ $? -ne 0 ]; then
    echo "Error: Failed to create user or database. Check .env credentials."
fi

  3. Test connection as firmuser

    PGPASSWORD=$FIRM_PASSWORD psql -U $FIRM_USER -h $PG_HOST -p $PG_PORT -d $PG_DB

    Exit with exit

  4. Update .env with database credentials

    Edit .env to use the new user for server operations:

    vim .env
# Set: PG_USER=$FIRM_USER, PG_PASSWORD=$FIRM_PASSWORD
# Re-export variables
set -a; source .env; set +a

  5. Initialize the database

    Run the server to create tables and apply the schema:

    go run main.go

Testing

  1. Reset database for schema changes (test mode)

    Drop and reinitialize the database for schema updates. Requires typing eraseDB to confirm:

    ./scripts/reset_db.sh
# WARNING: DELETES ALL DATA! Type 'eraseDB' when prompted.

Configuration

  1. Edit firm.conf

    Configure non-sensitive settings:

    vim firm.conf
# Example settings:
# [settings]
# cleanup_interval = "10s"
# inbound_method = "webhook"

Running

To be completed with instructions for running the server.

Mailgun/Gmail Setup

To be completed with steps for configuring webhooks and IMAP.

Troubleshooting

To be added with common issues and solutions.