Skip to main content

Frequently Asked Questions

Common questions and answers about EZ-Console.

General​

What is EZ-Console?​

EZ-Console is a full-stack framework for building enterprise management systems. It provides backend (Go) and frontend (React) with authentication, authorization, and audit logging built-in.

Is EZ-Console free?​

Yes, EZ-Console is open-source under the Apache License 2.0.

What databases are supported?​

SQLite (default), MySQL/MariaDB, and PostgreSQL.

Installation​

How do I install EZ-Console?​

go get github.com/sven-victor/ez-console@latest

See the Quick Start for prerequisites, encryption key usage, and optional CLI scaffolding.

What are the prerequisites?​

  • Go 1.20+
  • Node.js 18+
  • pnpm

Development​

How do I create a new controller?​

See Creating Controllers.

How do I add a new page to the frontend?​

See Application Shell.

How do API authentication and permissions work?​

On the standard API router group, routes require a logged-in user by default (the framework registers WithAuthentication on the group). You normally do not add middleware.RequireAuth() per handler for that behavior.

  • Public (no login) routes: wrap the group with middleware.WithoutAuthentication(router.Group(...)) so the opt-out middleware runs before the default authentication middleware. See Middleware: public routes.
  • Stricter than “any logged-in user”: add middleware.RequirePermission("resource:action") (or RequireAnyPermission / RequireAllPermissions) on the route or subgroup. See Middleware: permission checks.

JWT, OAuth, LDAP, MFA, and RBAC naming are covered in Authentication & Authorization. Controller registration context: Creating controllers and Core concepts.

Configuration​

Where is the encryption key used?​

The encryption key is used to encrypt sensitive data in the database (passwords, tokens, etc.).

Can I change the encryption key later?​

No! Never change the encryption key after initial setup, or all encrypted data will become unrecoverable.

How do I configure the database?​

See Database Configuration.

Deployment​

How do I deploy to production?​

See Deployment Strategies.

Should I use SQLite in production?​

SQLite is fine for small deployments (less than 100 concurrent users). For larger deployments, use MySQL or PostgreSQL.

How do I enable HTTPS?​

Use a reverse proxy (Nginx) with Let's Encrypt. See Deployment Strategies.

Security​

How are passwords stored?​

Passwords are hashed using bcrypt with salt.

How does authentication work?​

JWT-based stateless authentication. See Authentication & Authorization; default API login behavior and public routes are in Middleware.

How do I enable MFA?​

As a user: open Profile Center → Two-Factor Authentication, choose TOTP or E-mail, then follow the wizard (scan the QR code or copy the secret, enter the 6-digit code to verify). See Authentication & Authorization: MFA.

Administrators configure enforcement and related policies under System → Settings (security / MFA options); see Security settings.

Troubleshooting​

Server won't start​

  • Check if port 8080 is available
  • Verify encryption key is correct length (8, 16, 24, or 32 bytes)
  • Check database connection

Frontend won't connect to backend​

  • Ensure backend is running on port 8080
  • Check Vite proxy configuration
  • Verify CORS settings

Database migration failed​

  • Check database credentials
  • Ensure database exists
  • Check user permissions

"Invalid auth token" error​

  • Token may be expired, or the client did not send credentials on a protected route
  • For routes meant to be public, confirm they are registered under middleware.WithoutAuthentication(...) (see Middleware)

Performance​

How many users can EZ-Console handle?​

Depends on your infrastructure. With proper configuration:

  • SQLite: 10-100 concurrent users
  • MySQL/PostgreSQL: 1000+ concurrent users
  • With load balancing: 10,000+ users

How do I improve performance?​

  • Use connection pooling
  • Enable database indexes
  • Implement caching (Redis)
  • Use CDN for static assets
  • See Performance Tuning

Integration​

Can I integrate with existing systems?​

Yes! EZ-Console can be integrated with:

  • OAuth2/OIDC providers
  • LDAP/Active Directory
  • External APIs
  • Custom authentication systems

Can I use EZ-Console as a library?​

Yes, import specific packages as needed:

import "github.com/sven-victor/ez-console/pkg/api"
import "github.com/sven-victor/ez-console/pkg/service"

Getting Help​

Where can I get help?​

How do I report a bug?​

Open an issue on GitHub Issues with:

  • EZ-Console version
  • Go version
  • Steps to reproduce
  • Expected vs actual behavior
  • Error messages/logs

How do I request a feature?​

Open a feature request on GitHub Issues or discuss in GitHub Discussions.

Contributing​

How can I contribute?​

See the Contributing Guide.

Where is the source code?​

https://github.com/sven-victor/ez-console

Don't see your question? Ask in GitHub Discussions!