Installation Guide

Developer Beginner

This guide will help you set up your development environment for EZ-Console.

Prerequisites

Before installing EZ-Console, ensure you have the following installed:

Required Software

1. Go (1.20 or higher)

Check if installed:

go version
# Should output: go version go1.20.x or higher

Install Go:

• macOS: brew install go
• Linux: Download from golang.org/dl
• Windows: Download installer from golang.org/dl

Configure GOPATH (if needed):

export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

2. Node.js (18 or higher)

Check if installed:

node --version
# Should output: v18.x.x or higher

Install Node.js:

• macOS: brew install node
• Linux: Use NodeSource
• Windows: Download from nodejs.org

3. pnpm (Package Manager)

Check if installed:

pnpm --version

Install pnpm:

npm install -g pnpm

Or via alternative methods.

4. Git

Check if installed:

git --version

Install Git:

• macOS: brew install git
• Linux: sudo apt-get install git or sudo yum install git
• Windows: Download from git-scm.com

Optional but Recommended

Make (Build Automation)

Check if installed:

make --version

Install Make:

• macOS: Pre-installed with Xcode Command Line Tools
• Linux: sudo apt-get install build-essential
• Windows: Use MinGW or Chocolatey

Docker (For Production Deployment)

Check if installed:

docker --version
docker-compose --version

Install Docker:

• Download Docker Desktop from docker.com

Installation Methods

You have two options for using EZ-Console:

Option 1: Run the Framework Demo

This option lets you explore all built-in features by running the framework itself.

Clone the Repository

git clone https://github.com/sven-victor/ez-console.git
cd ez-console

Build the Application

Using Make:

make clean build

Manual Build:

# Backend
cd backend
go mod download
go build -o ../dist/server cmd/server/main.go

# Frontend
cd ../web
pnpm install
pnpm build

Run the Server

# Run with encryption key
./dist/server --global.encrypt-key=your-secret-key-16bytes

# Or with config file
./dist/server --global.encrypt-key=your-secret-key-16bytes --config config.yaml

Encryption Key

The --global.encrypt-key must be 8, 16, 24, or 32 bytes. This key encrypts sensitive data in the database. Never change it after initial setup or existing encrypted data will be unrecoverable.

Access the Application

Open your browser and navigate to:

• Application: http://localhost:8080/console
• API Documentation: http://localhost:8080/swagger/index.html

Default Credentials:

• Username: admin
• Password: admin123

First Login

You'll be prompted to change the default password on first login. This is a security requirement.

Option 2: Create Your Own Application

This is the recommended approach for building your own system.

Step 1: Create Project Directory

mkdir my-admin-app
cd my-admin-app
mkdir -p backend/controller backend/service web/src/pages

Step 2: Initialize Backend

cd backend
go mod init github.com/yourusername/my-admin-app
go get github.com/sven-victor/ez-console@latest

Step 3: Create Main Entry Point

Create backend/main.go:

package main

import (
    _ "github.com/yourusername/my-admin-app/controller"
    
    consoleserver "github.com/sven-victor/ez-console/server"
)

const VERSION = "1.0.0"

var rootCmd = consoleserver.NewCommandServer(
    "my-admin-app",
    VERSION,
    "My Enterprise Management System",
)

func main() {
    rootCmd.Execute()
}

Step 4: Initialize Frontend

cd ../web

Create web/package.json:

{
  "name": "my-admin-app-web",
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "ahooks": "^3.9.6",
    "antd": "^5.14.1",
    "ez-console": "github:sven-victor/ez-console.git#v1.9.1&path:web",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@types/node": "^20.11.19",
    "@types/react": "^18.2.55",
    "@types/react-dom": "^18.2.19",
    "@vitejs/plugin-react": "^4.2.1",
    "less": "^4.2.2",
    "typescript": "^5.3.3",
    "vite": "^5.1.0"
  }
}

Install dependencies:

pnpm install

Step 5: Create Basic Files

See the Quick Start Guide for complete code examples of:

• Vite configuration
• TypeScript configuration
• Main App component
• Entry point
• HTML template

Verify Installation

Verify Backend

cd backend
go run main.go --version
# Should output: my-admin-app version 1.0.0

Verify Frontend

cd web
pnpm dev
# Should start dev server on http://localhost:5173

Test API Connection

# Start backend (in one terminal)
cd backend
go run main.go --global.encrypt-key=test-key-16bytes

# In another terminal, test the API
curl http://localhost:8080/api/health
# Should return: {"status":"ok"}

Troubleshooting

Go Module Issues

Problem: go: module not found

Solution:

go mod tidy
go mod download

Port Already in Use

Problem: listen tcp :8080: bind: address already in use

Solution:

# Find process using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>

# Or use a different port
go run main.go --server.port=9090

Frontend Build Errors

Problem: Cannot find module 'ez-console'

Solution:

# Clear cache and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

Database Connection Issues

Problem: Database connection fails

Solution:

# SQLite (default) - check file permissions
ls -la *.db

# MySQL/PostgreSQL - verify connection string
go run main.go \
  --database.driver=mysql \
  --database.host=localhost \
  --database.port=3306 \
  --database.username=root \
  --database.password=password \
  --database.dbname=ez_console

Encryption Key Issues

Problem: encryption key must be 8, 16, 24, or 32 bytes

Solution:

# Use a key with valid length
go run main.go --global.encrypt-key=16-byte-key-here

# Or generate a secure key
openssl rand -base64 32 | cut -c1-16

Development Tools

Recommended IDE

• VS Code with extensions:

  • Go (official)
  • ES7+ React/Redux/React-Native snippets
  • ESLint
  • Prettier

• GoLand or WebStorm (JetBrains)

Useful Go Tools

# Install common Go tools
go install golang.org/x/tools/cmd/goimports@latest
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
go install github.com/swaggo/swag/cmd/swag@latest

Database Tools

• SQLite: DB Browser for SQLite
• MySQL: MySQL Workbench
• PostgreSQL: pgAdmin

Environment Configuration

Development Environment

Create .env file in backend directory:

# Server Configuration
SERVER_PORT=8080
SERVER_MODE=debug

# Database Configuration
DATABASE_DRIVER=sqlite
DATABASE_PATH=./ez-console-dev.db

# Log Configuration
LOG_LEVEL=debug
LOG_FORMAT=json

# Encryption Key (do not commit to git!)
GLOBAL_ENCRYPT_KEY=dev-key-16bytes

IDE Configuration

VS Code

Create .vscode/settings.json:

{
  "go.useLanguageServer": true,
  "go.lintTool": "golangci-lint",
  "go.lintOnSave": "workspace",
  "editor.formatOnSave": true,
  "[go]": {
    "editor.defaultFormatter": "golang.go"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

Next Steps

Now that you have EZ-Console installed:

1. Follow the Quick Start - Build your first application in 10 minutes
2. Understand Core Concepts - Learn key concepts before diving deep
3. Explore Examples - Check out the /demo directory for working examples
4. Read Backend Guide - Start backend development

Getting Help

If you encounter issues during installation:

1. Check the FAQ for common problems
2. Search GitHub Issues
3. Ask in GitHub Discussions
4. Review the Troubleshooting Guide

---

Installation successful? Continue to Quick Start to build your first application!