Local Development Environment

Ensure your local development environment meets the following requirements:

  • Golang v1.21+
  • Node v18.20+

Project Architecture

GeekAI is developed based on Go and Vue. The backend API web framework is built on Gin, and the frontend is developed using Element-Plus + Vant (for mobile).

Project Directory Structure

├── api # Backend API program
│   ├── bin # Compiled binaries
│   ├── core # Core service code
│   ├── handler # Handlers
│   ├── logger # Logging
│   ├── logs # Log directory
│   ├── res # Resource files
│   ├── service # Services
│   ├── static # Static files
│   ├── store # Storage-related code (e.g., Redis, MySQL, LevelDB)
│   └── utils # Utility functions
├── build # Build scripts
├── database # Database SQL files
├── desktop # Desktop wrapper application (Electron-based)
├── docker # Docker deployment (docker-compose.yaml)
│   ├── conf # Configuration files
│   └── data # Data files
└── web # Frontend application
    ├── dist # Compiled files
    ├── public # Static files
    └── src # Frontend source code
      ├── assets # Static resources
      ├── components # Components
      ├── lib # Libraries
      ├── store # State management (session, local storage)
      ├── utils # Utility functions
      └── views # View files

Backend Setup

First, clone the project:

# If you haven't installed Git, install it first
brew install git # macOS
yum install git # CentOS
apt install git # Ubuntu

# Clone the project
git clone https://github.com/yangjian102621/geekai.git
cd geekai/api

Second, create a configuration file. We provide a sample configuration file; you just need to copy config.sample.toml:

cp config.example.toml config.toml

Next, modify the MySQL and Redis connection details.

Third, run the Go program:

go run main.go

If you encounter dependency download timeouts or failures, such as the following error:

Dependency Download Timeout

You can try using a mirror in China. There are two ways to set this up:

  1. Export the environment variable directly:
export GOPROXY=https://goproxy.cn,direct
  1. Set the compilation environment variable using go env:
go env -w GOPROXY=https://goproxy.cn,direct

If you want to enable hot reloading (automatic API service restart on changes), you can use the fresh tool.

First, install fresh:

go get github.com/pilu/fresh
# If installation fails, try the following command
go install github.com/pilu/fresh@latest

Then use fresh to enable hot reloading for the Go application (execute in the api directory):

fresh -c fresh.conf

The default API service address is http://localhost:5678.

Frontend Setup

First, install the dependencies:

cd web
# Install dependencies
npm install
# If it's slow, you can use cnpm or pnpm
npm install -g cnpm
cnpm install

After installing the dependencies, start the frontend service:

npm run dev

Once started, access http://localhost:8888 to preview.

Docker Image Build

When the product is ready for production deployment, we recommend packaging the runtime and environment into a Docker image and running GeekAI using Docker.

Video Tutorial:

If you prefer learning through videos, watch the Bilibili tutorial GeekAI SD Configuration and Upgrade for Secondary Development.

  1. Build the API application:
# Compile first
cd api
make clean amd64
# Then build the Docker image
cd ../build
docker build -t geekai-api:$version -f dockerfile-api-go ../

Replace $version with your desired version number (e.g., v3.2.2).

  1. Build the frontend application:
cd web
# Install dependencies
npm install
# Compile
npm run build
# Build the Docker image
cd ../build
docker build -t geekai-web:$version -f dockerfile-vue ../
  1. Export the built images and import them on the production server:
# Export the images
docker save geekai-api:$version > geekai-api.tar
docker save geekai-web:$version > geekai-web.tar
# Copy to the production server
scp geekai-api.tar geekai-web.tar [email protected]:/opt
# Log in to the production server
ssh [email protected]
cd /opt
# Import the images
docker load < geekai-api.tar
docker load < geekai-web.tar

Push to Image Registry

If you find the above process (compile, build, copy, import) too cumbersome, a simpler solution is to push the images directly to your registry from your local machine and pull them on the production server.

We have prepared a one-click script for compiling, building, and pushing images in build/build.sh. You need to modify a few things (mainly replacing registry.cn-shenzhen.aliyuncs.com/geekmaster with your registry address):

#!/bin/bash

version=$1
arch=${2:-amd64}

# Build the Go API program
cd ../api
make clean $arch

# Build the web app
cd ../web
npm run build

cd ../build

# Replace registry.cn-shenzhen.aliyuncs.com/geekmaster with your registry address
docker rmi -f registry.cn-shenzhen.aliyuncs.com/geekmaster/geekai-api:$version-$arch
# Build the Docker image for geekai-go
docker build -t registry.cn-shenzhen.aliyuncs.com/geekmaster/geekai-api:$version-$arch -f dockerfile-api-go ../

# Build the Docker image for geekai-web
docker rmi -f registry.cn-shenzhen.aliyuncs.com/geekmaster/geekai-web:$version-$arch
docker build --platform linux/amd64 -t registry.cn-shenzhen.aliyuncs.com/geekmaster/geekai-api-web:$version-$arch -f dockerfile-vue ../

if [ "$3" = "push" ];then
  docker push registry.cn-shenzhen.aliyuncs.com/geekmaster/geekai-api:$version-$arch
  docker push registry.cn-shenzhen.aliyuncs.com/geekmaster/geekai-web:$version-$arch
fi

After making the changes, log in to your Docker registry:

docker login --username={your_username} {your_registry_address, e.g., registry.cn-shenzhen.aliyuncs.com}

Once ready, you can compile, build, and push the images with one command:

# v4.0.9 is the version number
# amd64 is your system architecture (options: amd64, arm64)
# push specifies whether to push to the registry (omit for local testing)
 ./build.sh v4.0.9 amd64 push

After pushing successfully, you can pull the images on the production server. Modify the docker-compose.yaml file, replacing registry.cn-shenzhen.aliyuncs.com/geekmaster with your registry address and v4.0.7 with your version number.

# Backend API program
geekai-api:
  image: registry.cn-shenzhen.aliyuncs.com/geekmaster/geekai-api:v4.0.7-amd64
  container_name: geekai-api
  restart: always
  depends_on:
    - geekai-mysql
    - geekai-redis
  environment:
    - DEBUG=false
    - LOG_LEVEL=info
    - CONFIG_FILE=config.toml
  ports:
    - '5678:5678'
    - '9999:9999'
  volumes:
    - /usr/share/zoneinfo/Asia/Shanghai:/etc/localtime
    - ./conf/config.toml:/var/www/app/config.toml
    - ./logs/app:/var/www/app/logs
    - ./static:/var/www/app/static
    - ./data/leveldb:/var/www/app/data

# Frontend application
geekai-web:
  image: registry.cn-shenzhen.aliyuncs.com/geekmaster/geekai-web:v4.0.7-amd64
  container_name: geekai-web
  restart: always
  depends_on:
    - geekai-api
  ports:
    - '8080:8080'
  volumes:
    - ./logs/nginx:/var/log/nginx
    - ./conf/nginx/conf.d:/etc/nginx/conf.d
    - ./conf/nginx/nginx.conf:/etc/nginx/nginx.conf
    - ./conf/nginx/ssl:/etc/nginx/ssl

After making the changes, restart the containers. Done! 🎉🎉🎉

API Documentation

GeekAI provides detailed API documentation, which you can find at https://geekai.apifox.cn. The documentation is updated as features evolve.