go-admingo-admin
  • Guide
  • Development
    • Advanced
    • Commands
  • Advanced
  • Help
  • GitHub
  • Changelog
⌘ K
Introduction
Quick Start
Go Environment
Go Modules
Environment Variables
Node Environment
IDE Setup
Conventions
Deployment
FAQ
Last updated:
Open-source MIT Licensed | Copyright © 2020-present
Powered by go-admin-team

TABLE OF CONTENTS

‌
‌
‌
‌

go-admin is split into a backend and a frontend, started separately: the backend go-admin and the frontend go-admin-ui. This page covers the backend first, then the frontend.

Here's the overall flow before diving in:

StageStepNotes
BackendPrerequisitesGo 1.26+, Go Modules enabled
BackendClone and buildclone the repo, run go build
BackendConfigure the data sourceedit the database connection in config/settings.yml
BackendCreate the databasean empty database, utf8mb4 charset
BackendInitialise datamigrate creates tables and seeds initial data
BackendStart the servicelistens on port 8000 by default
FrontendPrerequisitesNode 22+, pnpm 9+
FrontendClone and installclone the repo, run pnpm install
FrontendStartlistens on port 9527 by default

The whole thing takes about 20 minutes when it goes smoothly, most of it spent downloading dependencies. Have a database ready beforehand — MySQL 8.0 or later is recommended.

Prerequisitesgo-admin

INFO

Go version >= 1.26 (whatever go.mod in the repository declares takes precedence), with GO111MODULE=on (Go Modules mode).

Configuring Go environment variables

Download the API Projectgo-admin

bash
# working directory
$ mkdir myproject && cd myproject


# clone
$ git clone https://github.com/go-admin-team/go-admin.git


# build
$ cd ./go-admin
$ go mod tidy
$ go build

Configure the Data Sourcego-admin

  1. Use the repository's own config file directly — just edit the data source in config/settings.yml.
  2. Or copy it under a different name (e.g. config/settings.dev.yml) and point to it at startup with -c, which makes it easy to keep multiple environments apart.
yml
database:
  # database type: mysql, sqlite3, postgres
  driver: mysql
  # connection string; the mysql default shown here includes charset=utf8&parseTime=True&loc=Local&timeout=1000ms
  source: user:password@tcp(127.0.0.1:3306)/dbname?charset=utf8&parseTime=True&loc=Local&timeout=1000ms

WARNING

Using sqlite3 requires a build tag, or the program panics on startup:

bash
$ go build -tags sqlite3
# or run directly
$ go run -tags sqlite3 . server -c config/settings.yml

The reason is that common/database/open.go carries //go:build !sqlite3 — without the tag, the binary is compiled without the sqlite3 driver and crashes at runtime on a nil function. The error message never mentions the build tag, so it's easy to mistake for an environment problem. The build-sqlite target in the Makefile exists for exactly this.

MySQL and PostgreSQL are unaffected.

WARNING

MySQL 8.0+ works best. Older versions can hit errors like Error 1071: Specified key was too long; max key length is 1000 bytes — adjust according to your local database version.

Why this happens:

MySQL limits the length of a single-column index. Under the myisam and innodb storage engines the limits are 1000 bytes and 767 bytes respectively.

Fix:

sh
# edit the config file
vim /etc/my.cnf


# add MySQL's default engine setting under [mysqld]
default-storage-engine=InnoDB


# restart the service
service mysqld restart

Drop the tables that the migration already created, then run the migration again — it should succeed.

Create the Database

For local development, creating the database with Docker is a convenient option:

docker run --name mysql -p3306:3306 -d -e MARIADB_ROOT_PASSWORD=123456 mariadb:latest

Then connect with user root / password 123456:

mysql -h 127.0.0.1 -p123456 -e 'create database dbname default charset utf8'

INFO

The database's default charset needs to be utf8.

Initialise Datago-admin

The project supports initialising the database schema and seed data via a command — the migrate command handles both:

bash
# initialise
# macOS or Linux
$ go run main.go migrate -c config/settings.yml


# Windows
$ go run main.go  migrate -c config\settings.yml

INFO

The repository's own config file is config/settings.yml. For local multi-environment isolation, copy it and point to the copy with -c — for example, config/settings.dev.yml for a development environment.

Start the Servicego-admin

Once initialisation is done, it's time to start the project — try ./go-admin server:

bash
# start the service
# macOS or Linux
$ go run main.go  server -c config/settings.yml


# Windows
$ go run main.go  server -c config\settings.yml

If you see output like this, check your database configuration:

bash
2020-07-31 16:09:41.989 [INFO] Logger init success!
2020-07-31 16:09:41.990 [INFO] mysql-drive.go:20: user:password@tcp(127.0.0.1:3306)/dbname?charset=utf8&parseTime=True&loc=Local&timeout=1000ms
2020-07-31 16:09:44.350 [FATA] mysql-drive.go:23: mysql connect error : dial tcp 127.0.0.1:3306: connect: connection refused

Output like the image below means success — congratulations!

Next up, start the frontend!

WARNING

This is where the second stage begins.

Verify the Environmentgo-admin-ui

The frontend requires Node 22+ and pnpm 9+ (whatever the engines field in package.json declares takes precedence):

bash
$ node -v
v22.14.0


$ pnpm -v
9.15.1

WARNING

The project manages dependencies with pnpm, and pnpm-lock.yaml is committed to the repository. Installing with npm or yarn ignores that lockfile and may pull dependency versions that don't match CI.

If pnpm isn't installed yet: npm install -g pnpm, or use Node's built-in corepack enable.

Installing Node

Next, leave the go-admin project directory. We recommend keeping the go-admin and go-admin-ui project roots as siblings, in the same parent directory.

bash
$ ls
go-admin      go-admin-ui


# back to the parent directory
$ cd ../

Download the View Projectgo-admin-ui

Clone it directly:

bash
# clone
$ git clone https://github.com/go-admin-team/go-admin-ui.git

Output:

bash
$ git clone https://github.com/go-admin-team/go-admin-ui.git
Cloning into 'go-admin-ui'...
...
Receiving objects: 100% (584/584), 580.92 KiB | 16.00 KiB/s, done.
Resolving deltas: 100% (127/127), done.

The go-admin-ui code is now downloaded.

Install Dependenciesgo-admin-ui

bash
$ cd go-admin-ui/


$ pnpm install


# if the default registry is slow, point at a mirror
$ pnpm install --registry=https://registry.npmmirror.com

INFO

Restoring the package set can take a little while — hang tight.

Output like this means it installed successfully:

bash
Packages: +1653
Progress: resolved 1653, reused 1653, downloaded 0, added 1653, done


Done in 21.4s

Start the Viewgo-admin-ui

Start the project with pnpm dev:

bash
# start the dev server
$ pnpm dev

Output:

bash
VITE v8.2.1  ready in 722 ms


  ➜  Local:   http://localhost:9527/
  ➜  Network: use --host to expose

INFO

To let other devices on the LAN access it, run pnpm dev --host.

INFO

The project is running now, but check one thing: is go-admin (the backend) also running? Otherwise the page will show errors.

Build and Deploy

Kick off the build with pnpm build:prod:

bash
# build the project
$ pnpm build:prod


vite v8.2.1 building for production...
✓ built in 18.42s

The build output goes to ./dist by default; inspect it with tree (Windows users can skip this step).

Test environment verification: upload ./dist to a test environment and verify it there.

Deployment: upload the verified ./dist to the final or production environment.

For the full production deployment path (systemd, Docker, Nginx configuration), see Deployment.

What Counts as a Successful Start

Check off every item — all of them need to hold:

  1. The backend console printed its startup log with no mysql connect error-style errors;
  2. Visiting http://localhost:9527 in a browser shows the login page;
  3. Signing in with admin / 123456 works;
  4. The sidebar expands normally, and opening any page (e.g. "User Management") shows list data.

Step 4 is the one that matters. Seeing the login page only proves the frontend is running; seeing list data is what proves the frontend and backend are actually connected and the database was initialised correctly.

Stuck? Check These First

SymptomCheck first
Backend fails immediately with mysql connect errorUsername, password, database name and port in the config file; whether the database was actually created
Startup panics with something sqlite-relatedsqlite requires the build tag: go run -tags sqlite3 .
Login page loads, but signing in gives a network errorWhether the backend is running; whether the frontend's .env.development API address points at it
Login succeeds but the menu is emptyWhether migrate ran successfully and seeded the initial data
Pages load but lists return permission errorsWhether the current account's role has the relevant menu and API permissions assigned
Frontend dependency install failsWhether Node is 22 or later; delete node_modules and reinstall, but don't delete pnpm-lock.yaml

More errors are covered in the FAQ; if you're still stuck, see Getting Help for what to include in an issue.

WARNING

Where to get help: If anything in this guide is unclear, please open an issue.