Guide
In this guide, we explain general aspects of Go4lage. The main idea is that classic documentation is unnecessary as the code is so simple. Just read the source code and see how this documentation is made as well.
Environment File Explanation
When developing or deploying Go4lage, you need to adjust the .env file. As shown in the setup, there are three .env files prepared: one for native development, one for Docker development, and one for production (also Docker-based).
# .env
DB_URL=postgres://go4lage:go4lage@localhost:5432/go4lage?sslmode=disable
GOOSE_DBSTRING="user=go4lage password=go4lage dbname=go4lage sslmode=disable"
GOOSE_DRIVER=postgres
BASEURL=http://127.0.0.1
APIURL=http://localhost
PORT=8080
APIPORT=
USER_TOKEN_VALID_MINS=2400
SUPERUSER_2FA=false
SUPERUSER_TOKEN_VALID_MINS=600
LOGINTHROTTLE_TIME_S=1
DEBUG=true
DB_URL=postgres://go4lage:go4lage@db:5432/go4lage?sslmode=disable
This is the information for the Postgres driver: username, password, database, host, port.
GOOSE_DBSTRING="host=db user=go4lage password=go4lage dbname=go4lage sslmode=disable"
This is the information for the built-in Goose driver.
GOOSE_DRIVER=postgres
This specifies the database driver for Goose.
BASEURL=http://127.0.0.1
Your base URL. Change this to https://example.com for production.
APIURL=http://localhost
Your API URL. Change this to your API URL (needed for more complex setups).
PORT=8080
The port of this app. Make this consistent with the Docker build.
APIPORT=8080
The API port of this app. This is most likely empty for dockerized builds.
USER_TOKEN_VALID_MINS=2400
Specifies how long a bearer token for a user is valid. After this time, the user has to log in again.
SUPERUSER_2FA=true
If true, then 2FA for superusers is mandatory. If you activate this later, you'll have to create new superusers.
SUPERUSER_TOKEN_VALID_MINS=600
Similar to USER_TOKEN_VALID_MINS, but for superusers. It could be set to a shorter time for security reasons.
LOGINTHROTTLE_TIME_S=1
This is the auth throttle time. One IP address has to wait this value in seconds before it can try to log in again after entering wrong credentials.
DEBUG=true
If debug is true, the frontend will receive error details. This is useful for debugging and development but should be turned off for production.
Go4lage as Static File Server
In the directory, there is a 'root' folder. Go4lage will copy the content from this folder into the cache. It will replace components with a Jinja-like syntax and will replace API endpoints accordingly.
-
index.html
is the default entry point for the plain URL. -
The
admin/
folder is the default folder for the admin dashboard.
The files are also cache-busted - they are renamed at startup, and a random string is added so you can cache aggressively with your main reverse proxy.
Go4lage serving react vite
Go4lage can serve a react vite pwa directly. But this it not a must as a pwa can be served from another url as well.
For this to happen, simply adjust the vite config to build in the root folder and disable vite's cache busting and use an app name instead. Go4lage has it's own cache busting.
#vites.config.ts
export default defineConfig({
plugins: [react()],
build: {
outDir: '../root',
emptyOutDir: false,
rollupOptions: {
output: {
entryFileNames: 'assets/[name]-app.js',
chunkFileNames: 'assets/[name]-app.js',
assetFileNames: 'assets/[name]-app.[ext]',
},
},
},
})
In the API class or function you need to have the const apiUrlstring = '{ % Apiurl % }'
without space. This will be automatically replaced in production code with the Api url and still work in dev mode.
#api.tsx
class API {
apiUrl: string
constructor() {
const apiUrlstring = '{ %A piurl % }' // without space
const trimmedString = apiUrlstring.slice(2, -2).trim()
if (trimmedString === 'Apiurl') {
this.apiUrl = 'http://127.0.0.1:8080/adminapi'
} else {
this.apiUrl = apiUrlstring + '/adminapi'
}
}
Go4lage build in commands
Go4Lage comes with CLI commands that are powered by cobra. That help you to develop or to get things done. They are defined in the main.go
file.
startserver
./go4lage startserver
This starts the server. It is often used straight after build: go build && ./go4lage startserver
createsuperuser
./go4lage createsuperuser
This creates a superuser. Use this at least one time, then you can use the /admin
dashboard
createfakeusers
./go4lage createfakeusers 100
This creates 100 fakeusers for testing.
setupgp
./go4lage setupgp
This creates hard coded groups and permissions. It is only aditive and will not delete anything.
rungoose
This is your wrapper on the database. you can very simple reset your data or remigrate with this. Those are the most important, and even faster than switching a sqlLite db.:
./go4lage rungoose up
./go4lage rungoose down
This runs one downmigration, you have to confirm this with y.
Nginx config
Go4lage can run with any reverse proxy or even without one. However I recommend using nginx for SSL and as a balancer if you want to run more than just one instance of Go4lage on a server.
We warmly recommend certbot https://certbot.eff.org/ for SSL.
This is Go4lages Nginx config, you can probably cache for longer...:
#nginx config
server {
listen 80;
server_name go4lage.com www.go4lage.com;
return 301 https://go4lage.com$request_uri;
}
server {
listen 443 ssl;
server_name www.go4lage.com;
ssl_certificate /etc/letsencrypt/live/go4lage.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/go4lage.com/privkey.pem;
return 301 https://go4lage.com$request_uri;
}
server {
listen 443 ssl;
server_name go4lage.com;
client_max_body_size 10M;
ssl_certificate /etc/letsencrypt/live/go4lage.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/go4lage.com/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
add_header Cache-Control "public, max-age=3600";
location / {
proxy_pass http://127.0.0.1:8088;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}