Skip to content

Deployment Guide

Jump to bottom
yaojingang edited this page May 7, 2026 · 1 revision

Deployment Guide

This guide explains how to deploy GEOFlow from scratch, including server requirements, network requirements, Docker deployment, non-Docker PHP-FPM deployment, reverse proxy setup, subdirectory deployment, first login, and password changes.

For a short pre-launch checklist, see Deployment Checklist. If this is your first installation, start here.

1. What You Are Deploying

GEOFlow is not only a static website or a simple CMS. A complete deployment includes:

  • public content website
  • admin backend
  • PostgreSQL database
  • Redis cache and queue backend
  • scheduler process
  • queue worker process
  • optional Reverb WebSocket service
  • AI model API calls
  • file uploads and local storage

Do not validate only the web page. You also need to confirm database access, Redis, queue workers, scheduler, storage permissions, and AI API connectivity.

2. Server Requirements

Minimum Test Setup

Suitable for local testing, demos, and very low-volume content generation.

Item Recommendation
CPU 2 vCPU
Memory 2 GB RAM, plus 2 GB swap recommended
Disk 20 GB SSD
OS Ubuntu 22.04 / 24.04, Debian 12, or Rocky Linux 9
Network Stable outbound HTTPS access to your AI model provider
Usage Low concurrency, small tasks

Avoid 1 vCPU / 1 GB machines for anything beyond a quick experiment. PostgreSQL, Redis, PHP, queue workers, and AI jobs can easily exhaust memory.

Small Production Setup

Suitable for a personal site, small team site, or low-to-medium frequency GEO content workflow.

Item Recommendation
CPU 2-4 vCPU
Memory 4 GB RAM
Disk 40-80 GB SSD
Network 5 Mbps+ and stable outbound HTTPS
Database Local PostgreSQL + pgvector or Docker-managed PostgreSQL
Workload Single site, small number of concurrent workers

Medium Production Setup

Suitable for multiple content categories, continuous task execution, and larger material libraries.

Item Recommendation
CPU 4-8 vCPU
Memory 8-16 GB RAM
Disk 100 GB+ SSD
Network 10 Mbps+
Database Local or separate PostgreSQL
Workload Multiple tasks, multiple model providers

Multi-Site or High-Volume Setup

Item Recommendation
CPU 8+ vCPU
Memory 16 GB+ RAM
Disk 200 GB+ SSD, or object storage for assets
Database Separate PostgreSQL with scheduled backups
Redis Separate Redis or managed Redis
Queue Multiple workers, optionally separated by queue

3. Network and Security Requirements

Inbound Ports

Port Purpose Recommendation
80 HTTP optional, useful for certificate issuance and redirect
443 HTTPS recommended for production
18080 default Docker web port preferably behind Nginx / reverse proxy
18081 default Reverb port do not expose unless needed
5432 PostgreSQL do not expose publicly
6379 Redis do not expose publicly

Outbound Network

GEOFlow needs outbound access to:

  • the AI model providers you configure
  • GitHub version.json for update reminders
  • optional third-party publishing or distribution APIs

If your server is in a restricted network environment, choose providers that are officially reachable from that environment. Do not treat provider connectivity failure as an application bug before testing outbound access.

HTTPS and Reverse Proxies

Production should normally use Nginx, Caddy, a hosting panel, or a cloud load balancer for HTTPS termination.

When using a reverse proxy, set:

APP_URL=https://your-domain.com
TRUSTED_PROXIES=*
BOOST_BROWSER_LOGS_WATCHER=false

For subdirectory deployment, for example:

https://example.com/wiki

the reverse proxy must forward X-Forwarded-Prefix: /wiki. Do not put wiki into ADMIN_BASE_PATH.

APP_URL=https://example.com/wiki
TRUSTED_PROXIES=*
ADMIN_BASE_PATH=geo_admin

Admin URL:

https://example.com/wiki/geo_admin/login

4. Recommended Production Deployment: Docker Compose

This is the recommended deployment path for most VPS and cloud servers.

Install Basic Tools

On Ubuntu / Debian:

sudo apt update
sudo apt install -y git curl ca-certificates

Install Docker and Docker Compose using your preferred method, then verify:

docker --version
docker compose version

Download GEOFlow

git clone https://github.com/yaojingang/GEOFlow.git
cd GEOFlow

Prepare Environment Variables

cp .env.prod.example .env.prod
vi .env.prod

At minimum, update:

APP_NAME=GEOFlow
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com
TRUSTED_PROXIES=*

DB_DATABASE=geo_flow
DB_USERNAME=geo_user
DB_PASSWORD=change-this-password

REDIS_PASSWORD=

ADMIN_BASE_PATH=geo_admin
WEB_PORT=18080
REVERB_EXPOSE_PORT=18081

Also confirm:

BOOST_BROWSER_LOGS_WATCHER=false
GEOFLOW_SESSION_TIMEOUT=2592000
GEOFLOW_UPDATE_CHECK_ENABLED=true

APP_KEY may be left empty for the container entrypoint to generate, or generated manually:

php artisan key:generate --show

Build and Start

Define a helper command:

export COMPOSE_PROD='docker compose --env-file .env.prod -f docker-compose.prod.yml'

First deployment:

$COMPOSE_PROD build
$COMPOSE_PROD up -d postgres redis
$COMPOSE_PROD up -d init
$COMPOSE_PROD up -d app web queue scheduler reverb

Check services:

$COMPOSE_PROD ps

Logs:

$COMPOSE_PROD logs -f app
$COMPOSE_PROD logs -f queue
$COMPOSE_PROD logs -f scheduler

Create the Default Admin

The production entrypoint does not automatically seed an admin user. After migrations are complete, run:

docker compose --env-file .env.prod -f docker-compose.prod.yml run --rm app php artisan db:seed --force

Default credentials:

Item Value
Username admin
Password password
Role super admin

Change the password immediately after login.

Access Admin

If WEB_PORT=18080:

http://SERVER_IP:18080/geo_admin/login

With HTTPS domain:

https://your-domain.com/geo_admin/login

With subdirectory /wiki:

https://your-domain.com/wiki/geo_admin/login

First Login Checklist

  1. change the default admin password
  2. configure site name, description, keywords, and frontend language
  3. configure at least one chat model
  4. configure an embedding model if RAG is needed
  5. add knowledge bases, keywords, titles, authors, and images
  6. create a small test task
  7. verify homepage, category page, article page, and Markdown rendering

Change Admin Password

Use the account icon in the admin header and open personal settings, or use:

User Management

Super admins can edit standard admin accounts and create new admins.

If an admin account is locked after failed login attempts:

docker compose --env-file .env.prod -f docker-compose.prod.yml run --rm app php artisan geoflow:admin-unlock admin

5. Development Docker Deployment

For local testing only:

git clone https://github.com/yaojingang/GEOFlow.git
cd GEOFlow
cp .env.example .env
docker compose build
docker compose up -d

Access:

http://localhost:18080
http://localhost:18080/geo_admin/login

The development Compose file uses php artisan serve. Production should use docker-compose.prod.yml.

6. Traditional Deployment: Nginx + PHP-FPM + PostgreSQL + Redis

Use this only if you are comfortable managing Linux services manually.

Requirements

Component Requirement
PHP 8.2+, preferably 8.3 or 8.4
Composer 2.x
Database PostgreSQL 16, pgvector recommended
Redis Redis 7
Web server Nginx + PHP-FPM
PHP extensions pdo_pgsql, redis, curl, mbstring, xml, zip, bcmath, fileinfo, openssl

Install Application

git clone https://github.com/yaojingang/GEOFlow.git
cd GEOFlow
composer install --no-dev --optimize-autoloader
cp .env.prod.example .env

Edit .env:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com
TRUSTED_PROXIES=*

DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=geo_flow
DB_USERNAME=geo_user
DB_PASSWORD=your-password

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
QUEUE_CONNECTION=redis
CACHE_STORE=redis

Initialize:

php artisan key:generate
php artisan migrate --force
php artisan db:seed --force
php artisan storage:link
php artisan optimize

Nginx Root Must Be public

Document root:

/path/to/GEOFlow/public

Core Nginx example:

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/GEOFlow/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Long-Running Processes

Run these with Supervisor or systemd:

php artisan queue:work redis --queue=geoflow,default --sleep=1 --tries=1 --timeout=300
php artisan schedule:work

Optional Reverb:

php artisan reverb:start --host=0.0.0.0 --port=8080

7. Hosting Panels

For BT Panel, 1Panel, aaPanel, or similar environments:

  • prefer Docker / Compose deployment if available
  • if using PHP site mode, set the web root to public
  • ensure PHP 8.2+, PostgreSQL extension, and Redis extension are installed
  • do not use Docker-only DB_HOST=postgres unless running inside Compose
  • supervise queue workers and scheduler
  • ensure storage and bootstrap/cache are writable

Common issues:

Symptom Likely Cause
cannot resolve host postgres non-Docker deployment still uses Docker DB host
500 error APP_KEY, database, file permission, or cache issue
images fail missing storage:link or wrong document root
tasks do not run queue or scheduler not running
login redirects to wrong path APP_URL, trusted proxies, or forwarded prefix is wrong

8. Updates, Backups, and Rollbacks

Update

git pull
docker compose --env-file .env.prod -f docker-compose.prod.yml build
docker compose --env-file .env.prod -f docker-compose.prod.yml up -d
docker compose --env-file .env.prod -f docker-compose.prod.yml run --rm app php artisan migrate --force

If configuration changed:

docker compose --env-file .env.prod -f docker-compose.prod.yml run --rm app php artisan optimize:clear
docker compose --env-file .env.prod -f docker-compose.prod.yml up -d

Backup

Back up at least:

  • PostgreSQL database
  • .env.prod or .env
  • storage
  • uploaded assets

PostgreSQL example:

docker compose --env-file .env.prod -f docker-compose.prod.yml exec postgres \
  pg_dump -U geo_user geo_flow > geoflow-backup.sql

Rollback

git checkout <target-commit-or-tag>
docker compose --env-file .env.prod -f docker-compose.prod.yml build
docker compose --env-file .env.prod -f docker-compose.prod.yml up -d

If migrations have changed the database, check whether database restoration is required before rollback.

9. Pre-Launch Checklist

  • APP_DEBUG=false
  • APP_URL matches the real URL
  • TRUSTED_PROXIES matches the reverse proxy setup
  • BOOST_BROWSER_LOGS_WATCHER=false
  • default admin/password has been changed
  • PostgreSQL and Redis are not exposed publicly
  • queue and scheduler are running
  • at least one chat model passes connection testing
  • embedding model is configured if RAG is needed
  • homepage, category page, and article page work
  • image uploads and /storage/uploads/... URLs work
  • backups are prepared

10. Common Deployment Problems

Database Error: cannot resolve postgres

Non-Docker deployments should not use:

DB_HOST=postgres

Use the real database host instead:

DB_HOST=127.0.0.1

Inside Docker Compose, postgres is valid.

Login Redirects to the Wrong Root

Check:

  • APP_URL
  • TRUSTED_PROXIES
  • whether your reverse proxy sends X-Forwarded-Prefix
  • whether browser URL and APP_URL match

AI Model Test Fails

Check:

  • API Key
  • model type: chat or embedding
  • base URL vs full endpoint
  • outbound network access
  • provider failover behavior

Tasks Never Execute

Check:

docker compose --env-file .env.prod -f docker-compose.prod.yml ps
docker compose --env-file .env.prod -f docker-compose.prod.yml logs -f queue
docker compose --env-file .env.prod -f docker-compose.prod.yml logs -f scheduler

Usually either the queue worker or scheduler is not running.

Frontend Styles Fail

Check:

  • web root is public
  • static files are served correctly
  • browser console 404 errors
  • stale browser or view cache

11. Recommended Rollout Order

  1. validate Docker deployment locally or on a staging server
  2. configure domain and HTTPS
  3. change default admin password
  4. configure AI models and materials
  5. create one small task and verify the full workflow
  6. check frontend SEO, schema, and Markdown output
  7. run a small real-content batch
  8. increase automation only after stability is confirmed

The goal is not merely opening the admin page. A successful GEOFlow deployment means knowledge assets, models, queues, review, publishing, and frontend output form a stable workflow.

GEOFlow Repository · Changelog · 更新日志

中文

English

Clone this wiki locally