Go4lage logo

Go4lage Documentation

Setup

Go4lage is designed to run with Docker Compose, simplifying both development and production environments.

For development, we recommend using a native binary with Docker Compose for database management. This way you do not need to setup a native database on your system.

For testing on your local machine, you can run everything through Docker Compose.

For production deployment on your server, use the full Docker Compose configuration.

Select your preferred setup method below:

Native Go binary for Development

Prerequisites

These are the prerequisites for native, heavy development:

•

Install Git using the following command:

$ apt install git -y
•

Install Go by following the instructions at:

https://go.dev/doc/install
•

Install SQLC using the following command:

$ go install github.com/kyleconroy/sqlc/cmd/sqlc@v1.16.0
•

Install Docker by following the instructions at:

https://www.docker.com/
•

Install Docker Compose by following the instructions at:

https://docs.docker.com/compose/install/

Setup Steps

  1. Clone this repo.
  2. Navigate to the SQL package and generate SQL Queries with sqlc.
  3. Copy the native environment settings to the .env file.
  4. Adjust the .env file to your needs.
  5. Build the application.
  6. Make the dev script executable
  7. Start the db inside docker with a port open for the native binary
  8. Migrate your database.
  9. Create your superuser.
  10. Start the server.
  11. Visit the documentation at http://localhost:8080/
  12. Visit the admin dashboard at http://localhost:8080/admin

Quick Setup Script

#!/bin/bash
git clone https://github.com/Karl1b/go4lage.git
cd go4lage/pkg/sql
sqlc generate
cd ../..
cp nativeenv.env .env
go build
sudo chmod +x dev.sh
./dev.sh up -d
./go4lage rungoose up
./go4lage createsuperuser
./go4lage startserver

Congratulations, you've set up a native high-performance web service in less than 5 minutes 😊.

We recommend using the same database for production and development. With go4lage, it's really simple to do. You can use ./go4lage rungoose down to roll back one migration at a time(!) and up vice versa for all migrations. There's no need for a development-only SQLite database that you delete and recreate over and over.

Setting up a PWA with Vite and Go4lage

Go4lage includes a reference implementation of a React + Vite admin dashboard in the go4lage-admindashboard folder. You can use this as a starting point for your own PWA or study it to understand the integration pattern.

Project Structure

go4lage/
├── go4lage-admindashboard/  ← Vite project lives here
│   ├── src/
│   ├── vite.config.ts
│   └── package.json
│── root/                    ← Documentation lives currently here.
├── root/admin               ← Production build from vite outputs currently here
└── main.go

Development Workflow

During development, run Vite's dev server independently from Go4lage. This gives you hot module replacement and fast iteration. The frontend will make API calls to the Go4lage backend.

Prerequisites

We highly recommend using nvm for Node.js version management: https://github.com/nvm-sh/nvm

Running the Vite Dev Server

#!/bin/bash
# Navigate to your Vite project folder
cd go4lage-admindashboard
nvm use node
npm install
npm run dev

This starts the Vite dev server (typically on http://localhost:5173). Your frontend will make API calls to the Go4lage backend running on http://localhost:8080.

Production Build

When ready for production, build your Vite project and let Go4lage serve it as static files. Configure your vite.config.ts to output to Go4lage's root folder with custom file naming (Go4lage handles cache busting).

For detailed configuration instructions, see the React Vite Integration guide.

Two Deployment Options:

  • Integrated: Go4lage serves your built PWA from the /root folder (recommended for simple deployments and small to medium projects)
  • Separate: Deploy your PWA to a CDN or separate server and configure CORS (better for high-traffic apps or when you need independent scaling)

Variant with Docker (Compose) for Production

Prerequisites

These are the prerequisites for your Docker or production setup:

•

Install Git using the following command:

$ apt install git -y

Note: Git is optional. You need a way to copy the files to your server, whether you use git, ssh copy, or rsync.

•

Install Docker by following the instructions at:

https://www.docker.com/
•

Install Docker Compose by following the instructions at:

https://docs.docker.com/compose/install/

Setup Steps

  1. Clone this repo.
  2. Copy the Docker environment settings to the .env file.
  3. Adjust the .env file to your needs.
  4. Start the Docker Compose network.
  5. Hack inside the container and create your superuser.
  6. Visit the documentation at http://localhost:8080/
  7. Visit the admin dashboard at http://localhost:8080/admin

Quick Setup Script

#!/bin/bash
git clone https://github.com/Karl1b/go4lage.git
cd go4lage
cp dockerenv.env .env
docker-compose up -d
docker exec -it docu_app bash
./go4lage createsuperuser

Congratulations, you've set up a high-performance dockerized web service in less than 2 minutes 😊.

We recommend finishing the setup by running a native NGINX instance as the main reverse proxy.