Deployment Scripts Guide

Deployment Scripts Guide

This page explains how to use the reference deployment scripts in the GEOFlow deploy-scripts/ directory, what server environments they fit, what to prepare before execution, how to verify the deployment, and how to troubleshoot common failures.

The scripts are not a replacement for production operations, but they automate the repeated deployment path: host preflight checks, source download, production environment generation, Docker Compose production stack startup, default admin initialization, and post-deployment health checks.

1. Scripts

Script	Purpose	Recommended Use
geoflow-docker-deploy.sh	Production Docker one-click deployment	Fresh cloud servers, VPS, Docker hosts, panel servers such as BT Panel or 1Panel
geoflow-healthcheck.sh	Post-deployment health check	After deployment, domain/HTTPS/proxy changes, and upgrades

Script directory:

https://github.com/yaojingang/GEOFlow/tree/main/deploy-scripts

2. Recommended Server Environment

Minimum Test Environment

• CPU: 2 cores
• Memory: 2 GB RAM plus 2 GB swap
• Disk: 20 GB free
• OS: Ubuntu 22.04+, Debian 12+, Rocky Linux 9+, Alibaba Cloud Linux 3+
• Network: outbound access to GitHub, Docker registry, and your AI provider APIs

Small Production Environment

• CPU: 2-4 cores
• Memory: 4-8 GB
• Disk: 40-80 GB SSD
• Network: 5 Mbps+ public bandwidth
• Recommended: Nginx, Caddy, BT Panel, 1Panel, cloud load balancer, or CDN for HTTPS reverse proxy

Medium / Multi-Site Environment

• CPU: 4-8 cores or higher
• Memory: 8-16 GB or higher
• Disk: 100 GB+ SSD; use object storage or a separate disk for uploads when needed
• Database: dedicated PostgreSQL or managed cloud PostgreSQL is recommended
• Redis: dedicated Redis or managed cloud Redis is recommended

3. Before Running the Script

Check that:

• The server can access https://github.com/yaojingang/GEOFlow
• The server can pull Docker images
• Port 18080 is available, or you plan to customize it
• DNS is already pointed to the server if using a domain
• HTTPS reverse proxy can forward traffic to the Web port exposed by Docker
• PostgreSQL port 5432 and Redis port 6379 are not exposed publicly

If Docker image pulling is unstable in your region, configure a stable Docker registry mirror before running the script.

4. One-Command Deployment

Run on a fresh server:

curl -fsSL https://raw.githubusercontent.com/yaojingang/GEOFlow/main/deploy-scripts/geoflow-docker-deploy.sh -o geoflow-docker-deploy.sh
bash geoflow-docker-deploy.sh

The script will:

1. Check basic commands: git, curl, openssl
2. Check CPU, memory, and disk
3. Check Docker and Docker Compose v2
4. Offer to install Docker when missing
5. Clone or update GEOFlow source code
6. Generate and update .env.prod
7. Build production Docker images
8. Start PostgreSQL and Redis
9. Run Laravel initialization and migrations
10. Start Web, App, Queue, Scheduler, and Reverb
11. Seed the default admin
12. Clear and rebuild Laravel caches
13. Run post-deployment health checks

5. Interactive Parameters

The script asks for:

Parameter	Default	Description
APP_URL	http://server-ip:18080	Public URL, must include http:// or https://
Web port	18080	Host port mapped to the Web container
Reverb port	18081	Realtime service port
Admin base path	geo_admin	Admin login path, for example /geo_admin/login

If you have a domain, use:

https://example.com

If deploying under a first-level subdirectory:

https://example.com/wiki

Set APP_URL to:

https://example.com/wiki

Keep the admin base path as:

geo_admin

Do not set it to:

wiki/geo_admin

6. Non-Interactive Deployment

For cloud-init, server templates, or CI:

GEOFLOW_NONINTERACTIVE=1 \
GEOFLOW_APP_URL=https://example.com \
GEOFLOW_APP_DIR=/opt/geoflow \
GEOFLOW_WEB_PORT=18080 \
GEOFLOW_REVERB_PORT=18081 \
GEOFLOW_ADMIN_BASE_PATH=geo_admin \
bash geoflow-docker-deploy.sh

Common variables:

Variable	Default	Description
GEOFLOW_REPO_URL	https://github.com/yaojingang/GEOFlow.git	Source repository URL
GEOFLOW_BRANCH	main	Branch to deploy
GEOFLOW_APP_DIR	/opt/geoflow	Installation directory
GEOFLOW_APP_URL	detected IP	Public URL
GEOFLOW_WEB_PORT	18080	Web port
GEOFLOW_REVERB_PORT	18081	Reverb port
GEOFLOW_ADMIN_BASE_PATH	geo_admin	Admin base path
GEOFLOW_INSTALL_DOCKER	auto	1 to auto-install Docker; 0 to fail if Docker is missing
GEOFLOW_DB_DATABASE	geo_flow	PostgreSQL database name
GEOFLOW_DB_USERNAME	geo_user	PostgreSQL username
GEOFLOW_DB_PASSWORD	random	PostgreSQL password
GEOFLOW_REDIS_PASSWORD	random	Redis password
GEOFLOW_TRUSTED_PROXIES	*	Recommended for reverse proxy, CDN, and subdirectory deployments
GEOFLOW_SELF_DELETE	0	1 removes the executed deployment script after success

7. Self-Delete Mode

To remove the downloaded deployment script after a successful deployment:

GEOFLOW_SELF_DELETE=1 bash geoflow-docker-deploy.sh

This only removes the executed script file. It does not remove:

• Deployed GEOFlow source code
• Repository deploy-scripts/ directory
• Database data
• Uploads
• Containers

8. Access After Deployment

Default access:

Frontend: http://server-ip:18080
Admin:    http://server-ip:18080/geo_admin/login

Default admin:

Item	Value
Username	admin
Password	password

Change the default password immediately after the first login.

9. Change Admin Password

After logging in:

1. Open the user menu in the top-right corner.
2. Open account or user management.
3. Change the current admin password.

If the admin account is locked:

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

10. Health Check

The deployment script runs a health check automatically. You can also run it manually:

cd /opt/geoflow
bash deploy-scripts/geoflow-healthcheck.sh

It checks:

• Docker Compose service status
• PostgreSQL, Redis, App, Web, Queue, Scheduler, and Reverb
• http://127.0.0.1:WEB_PORT/up
• Laravel database migration status
• Recent App, Queue, Scheduler, and Web logs

11. Common Server Environments

Cloud Server / VPS

Use the one-command deployment script directly, then reverse proxy ports 80/443 to 127.0.0.1:18080.

BT Panel / 1Panel / Server Panels

Use Docker deployment for GEOFlow. Let the panel manage:

• Domain binding
• HTTPS certificates
• Reverse proxy
• Firewall ingress

Avoid using the panel to run GEOFlow as a native PHP site, because that may conflict with the Docker production stack.

Internal Network Server

If the server cannot access GitHub or Docker Hub, prepare:

• Internal Git mirror or uploaded source package
• Available Docker image mirror
• Network egress to AI provider APIs

Use a custom source repository:

GEOFLOW_REPO_URL=https://your-git-mirror/GEOFlow.git bash geoflow-docker-deploy.sh

Existing Nginx / Caddy Server

GEOFlow exposes its Web port, usually 18080. Proxy external traffic to it:

location / {
    proxy_pass http://127.0.0.1:18080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

12. Subdirectory Deployment

If the external URL is:

https://example.com/wiki

Use:

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

The reverse proxy should pass:

proxy_set_header X-Forwarded-Prefix /wiki;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;

The admin URL should be:

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

Not:

https://example.com/geo_admin/login

13. Upgrade

cd /opt/geoflow
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
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 run --rm app php artisan optimize

Back up before upgrading:

• .env.prod
• storage/
• PostgreSQL data directory or database dump

14. Troubleshooting

Docker Missing

The script can offer to install Docker. For controlled production environments, install Docker and Docker Compose v2 manually first.

Port Already Used

Use custom ports:

GEOFLOW_WEB_PORT=28080 GEOFLOW_REVERB_PORT=28081 bash geoflow-docker-deploy.sh

Docker Image Pull Failure

Usually caused by unstable registry access. Try:

• Retry
• Configure a stable registry mirror
• Check outbound network
• Test docker pull php:8.4-fpm-bookworm

Admin Cannot Open

Check:

• APP_URL
• ADMIN_BASE_PATH
• Reverse proxy target port
• X-Forwarded-Prefix for subdirectory deployments
• BOOST_BROWSER_LOGS_WATCHER=false

Tasks Do Not Run

Run:

cd /opt/geoflow
bash deploy-scripts/geoflow-healthcheck.sh

Focus on:

• queue
• scheduler
• Redis
• AI model API configuration

15. Security Notes

• Change the default admin password immediately.
• Use a custom admin path.
• Do not expose PostgreSQL or Redis publicly.
• Use HTTPS.
• Keep APP_DEBUG=false in production.
• Keep BOOST_BROWSER_LOGS_WATCHER=false in production.
• Back up database and uploads regularly.
• Delete temporary deployment scripts after use, or use GEOFLOW_SELF_DELETE=1.