First Run Configuration

This guide walks you through the initial configuration of NexAuth after your first startup.

What Happens on First Run

When you start NexAuth for the first time:

The plugin generates a default config.conf file
It automatically shuts down the server
This is normal - we need to configure it before full operation

The automatic shutdown after first startup is intentional. NexAuth generates a default configuration file that you should review before running the plugin.

Understanding the Generated Config

After first shutdown, you’ll find plugins/NexAuth/config.conf with these main sections:

# !!THIS FILE IS WRITTEN IN THE HOCON FORMAT!!
# The hocon format is very similar to JSON, but it has some extra features.

# Database configuration
database {
    type=nexauth-sqlite
}

# Premium auto-register
auto-register=false

# Profile conflict resolution
profile-conflict-resolution-strategy=BLOCK

# Default crypto provider (BCrypt-2A recommended)
default-crypto-provider=BCrypt-2A

# Debug mode
debug=false

# TOTP 2FA
totop {
    enabled=false
}

Essential Configuration Steps

1. Set Your Deployment Mode

Choose the correct mode for your setup:

# NexAuth works on both Velocity and Paper
# No mode configuration needed - single JAR works for both

2. Configure Online/Premium Mode

# Should we automatically register all players with a premium nickname?
auto-register=false

# Profile conflict resolution strategy
profile-conflict-resolution-strategy=BLOCK

Important: online-mode=false is required wherever NexAuth is installed.

Customize the commands players use:

# Commands that are allowed while the user is not authorized
allowed-commands-while-unauthorized=[
    login,
    register,
    "2fa",
    "2faconfirm",
    l,
    log,
    reg
]

4. Database Configuration

Tab Title
Tab Title
Tab Title

Perfect for small servers and development setups. No additional services required.

database {
    type=nexauth-sqlite
    sqlite {
        path="user-data.db"
    }
}

Advantages:

✅ No setup required
✅ No additional services
✅ Easy to backup (just copy the .db file)
✅ Good for small servers (< 100 players)

Recommended for medium to large servers and production environments.

database {
    type=nexauth-mysql
    properties {
        mysql {
            host=localhost
            database=nexauth
            password="your_password"
            port=3306
            user=root
        }
    }
}

Recommended for enterprise environments and servers requiring advanced features.

database {
    type=nexauth-postgresql
    properties {
        postgresql {
            host=localhost
            database=nexauth
            password="your_password"
            port=5432
            user=root
        }
    }
}

5. Adjust Registration Settings

# Sets the login/register time limit in seconds. Set to negative to disable.
seconds-to-authorize=-1

# The minimum length of a password. Set to negative to disable.
minimum-password-length=-1

# The minimum length the player's name can have.
minimum-username-length=-1

Advanced Configuration

TOTP Two-Factor Authentication

totp {
    # Should we enable TOTP-Based Two-Factor Authentication?
    enabled=true
    # The label to be displayed in the 2FA app.
    label="NexAuth Network"
    # The delay in milliseconds until player is given a map to scan the QR code.
    delay=1000
}

Debug Mode

Set debug level for troubleshooting:

# Should we enable debug mode? This will print out debug messages to the console.
debug=true

Only enable debug level 2 or 3 when troubleshooting. Higher debug levels can impact performance and generate large log files.

Rate Limiting

# Sets the maximum amount of accounts that can be registered from the same IP address.
# Set to zero or less to disable.
ip-limit=-1

# Kick the player, if the password was incorrect more or equal times. -1 means disabled
max-login-attempts=-1

After Configuration

Save and Test

Save your config.conf changes
Start your server (Velocity or Paper/Purpur)
Test with both premium and offline accounts

Verify Database Connection

Check your server logs for:

Database connection successful
No SQL errors
User table creation

Test Player Experience

Have players test:

Premium account auto-login
Offline account registration
Login commands
Any TOTP setup (if enabled)

Common Configuration Issues

Database Connection Failed

Check database server is running
Verify connection details
Ensure database user has proper permissions

Commands Not Working

Check for plugin conflicts
Verify command syntax in config
Check server logs for errors

Players Getting Kicked

Ensure online-mode=false is set correctly
Check register-delay is adequate
Verify no conflicting plugins

Recommended First Setup

Tab Title
Tab Title

Basic setup for new servers

# Basic setup for new servers
database {
    type=nexauth-sqlite
    sqlite {
        path="user-data.db"
    }
}
auto-register=false
profile-conflict-resolution-strategy=BLOCK
default-crypto-provider=BCrypt-2A
debug=true
minimum-password-length=-1
totp {
    enabled=false
}

Production-ready configuration

# Production-ready configuration
database {
    type=nexauth-mysql
    properties {
        mysql {
            host="db-server.example.com"
            database=nexauth_prod
            password="SECURE_PASSWORD_HERE"
            port=3306
            user=nexauth_user
        }
    }
}
auto-register=false
profile-conflict-resolution-strategy=BLOCK
default-crypto-provider=BCrypt-2A
debug=false
minimum-password-length=8
ip-limit=3
max-login-attempts=5
totp {
    enabled=false
}

Getting Help

If you run into issues:

Check the troubleshooting guides
Review database setup for database-specific issues
Check server logs for error messages
Visit GitHub Issues for support

Next Steps

Once you have the basic configuration working:

📖 Database setup for performance optimization
📖 Installation guides for deployment options
📖 Advanced configuration topics (coming soon)

Documentation Index

​First Run Configuration

​What Happens on First Run

​Understanding the Generated Config

​Essential Configuration Steps

​1. Set Your Deployment Mode

​2. Configure Online/Premium Mode

​3. Registration and Login Commands

​4. Database Configuration

​5. Adjust Registration Settings

​Advanced Configuration

​TOTP Two-Factor Authentication

​Debug Mode

​Rate Limiting

​After Configuration

​Save and Test

​Verify Database Connection

​Test Player Experience

​Common Configuration Issues

​Database Connection Failed

​Commands Not Working

​Players Getting Kicked

​Recommended First Setup

​Getting Help

​Next Steps

First Run Configuration

What Happens on First Run

Understanding the Generated Config

Essential Configuration Steps

1. Set Your Deployment Mode

2. Configure Online/Premium Mode

3. Registration and Login Commands

4. Database Configuration

5. Adjust Registration Settings

Advanced Configuration

TOTP Two-Factor Authentication

Debug Mode

Rate Limiting

After Configuration

Save and Test

Verify Database Connection

Test Player Experience

Common Configuration Issues

Database Connection Failed

Commands Not Working

Players Getting Kicked

Recommended First Setup

Getting Help

Next Steps