CaWittMN08/custom_ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: Installation / Upgrade on Brotherton Staging
Pages
Installation / Upgrade on Brotherton Staging
Clone
4
Installation / Upgrade on Brotherton Staging
CaWittMN08 edited this page 2025-12-13 04:10:35 +00:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Stage Deployment – Frappe Docker

This document describes how to deploy a new version of the Brotherton Frappe Docker image to the stage server, as well as what the deployment scripts do.

Prerequisites

Before starting, ensure all of the following are true:

  • You have a valid SSH key added to the authorized_keys of the stage server
  • You can SSH to the server as root
  • You are authenticated to the container registry:
docker login githaven.org
sudo docker login githaven.org
  • Docker is installed and running locally
  • You have permission to push images to:
githaven.org/shiloh/brotherton_frappe_docker

Deployment Steps (Human Workflow)

1. Clone the repository

git clone https://githaven.org/Shiloh/frappe_docker.git

2. Change into the repository

cd frappe_docker

3. Check the current image version

Navigate to the container registry and identify the current version tag:

https://githaven.org/Shiloh/-/packages/container/brotherton_frappe_docker

Determine the next version (typically incrementing the patch number).

Example:

  • Current: 1.4.7
  • Next: 1.4.8

4. Build and deploy the new version

Run the build script with the new tag:

./build_new.sh --tag 1.4.8

Optional (run database migrations during deploy):

./build_new.sh --tag 1.4.8 --migrate

5. Monitor the output

Watch for:

  • Docker build completion
  • Successful image push
  • SSH connection to the stage server
  • Remote deployment output

If any step fails, the script will stop and report the error.

Script Overview

There are two scripts involved:

  1. build_new.sh – runs locally
  2. re-deploy.sh – runs on the remote stage server

Script 1: build_new.sh (Local Machine)

Purpose

This script:

  • Builds a new Frappe Docker image
  • Pushes it to the container registry
  • Triggers a remote deployment over SSH

Argument Parsing

Supported arguments:

Argument Description
--tag Required. Version tag for the Docker image
--migrate Optional. Triggers database migrations on deploy
--remote-host Optional. Override default server (erpnext.lasthourhosting.org)
--remote-user Optional. Override default user (root)

If --tag is missing, the script exits immediately.

Environment Preparation

  • Exports the TAG environment variable

  • Base64-encodes apps_new.json into APPS_JSON_BASE64

    • This allows app configuration to be injected into the Docker build

Docker Build

The script performs a clean build:

  • --no-cache ensures no stale layers are reused
  • Uses Frappe version-15
  • Injects apps_new.json into the image
  • Tags the image as:
githaven.org/shiloh/brotherton_frappe_docker:<TAG>

Docker Push

Once built, the image is pushed to the registry:

docker push githaven.org/shiloh/brotherton_frappe_docker:<TAG>

This makes the image available to the stage server.

Remote Deployment Trigger

After a successful push:

  • The script SSHs into the stage server
  • Executes:
./re-deploy.sh --tag <TAG> [--migrate]

This hands off control to the remote deployment script.

Script 2: re-deploy.sh (Remote Stage Server)

Purpose

This script:

  • Updates Docker Compose to the new image version
  • Recreates containers
  • Runs Frappe build and migration steps
  • Cleans up old Docker images

Argument Parsing

Supported arguments:

Argument Description
--tag Required. Image version to deploy
--migrate Optional. Runs bench migrate

If --tag is missing, the script exits.

Update Docker Compose Version

  • Backs up frappe-compose.yml
  • Replaces the image tag:
brotherton_frappe_docker:<TAG>

This ensures Docker Compose pulls the correct image.

Stop Running Containers

docker compose down

This cleanly shuts down all running services.

Start Containers with New Image

docker compose up -d

Docker pulls the new image and starts fresh containers.

Detect Frontend Container

The script:

  • Searches running containers
  • Finds the first container matching frappe-frontend

This container is used for all subsequent bench commands.

Migration and Build Steps

Inside the frontend container:

  • If --migrate is set:

    • Runs bench migrate

  • Always runs:

bench build

This compiles assets and prepares the application.

Container Restart

To ensure JS pointers and assets reset correctly:

docker compose down
docker compose up -d

Final Frontend Build

Runs a site-specific frontend build:

bench build-frontend --site erpnext.lasthourhosting.org

This ensures production-ready frontend assets.

Old Image Cleanup

The script automatically removes the previous-previous image:

Example:

  • Deploying 1.4.8
  • Deletes 1.4.6 (if it exists)

This keeps disk usage under control while preserving rollback options.

Completion

When all steps succeed, the deployment is complete and the stage server is running the new version.

🎉 Deployment finished successfully