Pocketbase Dockerfile and deployment documentation #5253

halocline · 2025-08-05T17:11:58Z

Overview

Establishing a design system database to serve as a source of truth for the current state of the design system.
- Creating a Dockerfile to build and deploy the database on cloud infrastructure.
Introduces an apps directory as part of the monorepo structure. pocketbase_app is the first app. Future monorepo structure might resemble the following:

/apps
    /aries-site
    /design-system-manager
    /design-tokens-manager
    /ds-assistant
    /ds-mcp-server
    /pocketbase_app
/core
    /aries-core
/packages
    /design-tokens
    /hpe-icons
    /hpe-ui-library
/sandbox
    ...
package.json

Above structure is conceptual and discussion is welcome.

PR detail

This pull request introduces a complete setup for deploying the PocketBase backend for the HPE Design System to Google Cloud Run with persistent storage and production-ready configuration. It adds essential documentation, a Dockerfile for containerization, a startup script for efficient data handling, and proper licensing. The changes focus on enabling persistent, performant, and safe operation of PocketBase in a cloud environment.

Cloud Deployment & Data Persistence

Added a Dockerfile that builds a minimal Alpine-based container, downloads the PocketBase binary, sets up required directories, and uses a startup script to manage data and server startup.
Introduced a startup.sh script that copies the database from the mounted Cloud Storage volume to local storage on startup for performance, and backs up data to Cloud Storage on shutdown for persistence.
Updated .gitignore to exclude PocketBase binaries, data, logs, and temporary directories to keep the repository clean.

Documentation & Usage

Added a comprehensive DEPLOYMENT.md guide detailing step-by-step deployment to Google Cloud Run, including prerequisites, setup, admin access, architecture, troubleshooting, and best practices for SQLite persistence.
Provided a QUICK_REFERENCE.md with essential commands for deployment, admin credential reset, log checking, and key operational notes.
Updated README.md to explain the backend's purpose, PocketBase features, and a high-level overview of cloud deployment strategies, emphasizing Cloud Run with persistent storage.

Licensing

Added an LICENSE.md file with the MIT license for proper open-source compliance.

changeset-bot · 2025-08-05T17:12:01Z

⚠️ No Changeset found

Latest commit: dcde538

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

netlify · 2025-08-05T17:12:02Z

✅ Deploy Preview for hpe-theme-preview ready!

Name	Link
🔨 Latest commit	`dcde538`
🔍 Latest deploy log	https://app.netlify.com/projects/hpe-theme-preview/deploys/6893edf810b1370008d99166
😎 Deploy Preview	https://deploy-preview-5253--hpe-theme-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2025-08-05T17:12:03Z

✅ Deploy Preview for unrivaled-bublanina-3a9bae ready!

Name	Link
🔨 Latest commit	`dcde538`
🔍 Latest deploy log	https://app.netlify.com/projects/unrivaled-bublanina-3a9bae/deploys/6893edf810b1370008d99168
😎 Deploy Preview	https://deploy-preview-5253--unrivaled-bublanina-3a9bae.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Co-authored-by: Copilot <[email protected]>

Copilot

Pull Request Overview

This PR establishes a complete PocketBase cloud deployment infrastructure for the HPE Design System. It introduces the first app in the proposed monorepo structure with comprehensive Docker containerization, Google Cloud Run deployment scripts, and detailed documentation for cloud-based data persistence.

Creates complete PocketBase deployment infrastructure with Cloud Run integration
Introduces apps/pocketbase_app as the first application in a new monorepo structure
Provides automated deployment scripts and comprehensive documentation

Reviewed Changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
startup.sh	Container startup script with health checks and graceful shutdown handling
deploy.sh	Automated deployment script for Google Cloud infrastructure setup
cloud-run-service.yaml	Static Cloud Run service configuration for HPE Design System
cloud-run-service.template.yaml	Portable templated configuration with environment variable substitution
README.md	Project overview and quick start documentation
QUICK_REFERENCE.md	Essential commands and operations reference
LICENSE.md	MIT license for open-source compliance
Dockerfile.orig	Original Docker configuration preserved for reference
Dockerfile	Production-ready container build with security hardening
DEPLOYMENT.md	Comprehensive deployment guide with troubleshooting
CLOUD_STORAGE_SETUP.md	Detailed Cloud Storage integration documentation
CHANGELOG.md	PocketBase version changelog (v0.29.1)
.gitignore	Repository exclusions for binaries and generated files
.env.example	Environment configuration template

Copilot · 2025-08-06T23:31:15Z

apps/pocketbase_app/startup.sh

+    else
+        echo "⚠️  Data directory is not writable, attempting to fix permissions..."
+        # This might not work if we're not root, but it's worth trying
+        chmod 755 "$DATA_DIR" 2>/dev/null || true


Using chmod 755 on a data directory could expose sensitive database files to other users on the system. Consider using 750 or 700 for better security, as PocketBase data should only be accessible by the application user.

Suggested change

chmod 755 "$DATA_DIR" 2>/dev/null || true

chmod 700 "$DATA_DIR" 2>/dev/null || true

Copilot · 2025-08-06T23:31:16Z

apps/pocketbase_app/deploy.sh

+echo "🔐 Granting permissions to service account..."
+gcloud projects add-iam-policy-binding "$PROJECT_ID" \
+    --member="serviceAccount:$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
+    --role="roles/storage.admin"


Granting 'roles/storage.admin' provides broad permissions including the ability to delete buckets and modify IAM policies. Consider using 'roles/storage.objectAdmin' which provides sufficient permissions for PocketBase data operations without bucket-level administrative access.

Suggested change

--role="roles/storage.admin"

--role="roles/storage.objectAdmin"

Copilot · 2025-08-06T23:31:16Z

apps/pocketbase_app/cloud-run-service.yaml

+        autoscaling.knative.dev/maxScale: "1"
+    spec:
+      # Use the service account with Cloud Storage permissions
+      serviceAccountName: pocketbase-service-account@hpe-design-system-adoption.iam.gserviceaccount.com


The service account email is hardcoded with a specific project ID 'hpe-design-system-adoption'. This makes the configuration non-portable across different projects. Consider using the template version or environment variable substitution for better maintainability.

Suggested change

serviceAccountName: pocketbase-service-account@hpe-design-system-adoption.iam.gserviceaccount.com

serviceAccountName: pocketbase-service-account@${PROJECT_ID}.iam.gserviceaccount.com

Copilot · 2025-08-06T23:31:16Z

apps/pocketbase_app/cloud-run-service.yaml

+      # Use the service account with Cloud Storage permissions
+      serviceAccountName: pocketbase-service-account@hpe-design-system-adoption.iam.gserviceaccount.com
+      containers:
+      - image: gcr.io/hpe-design-system-adoption/pocketbase-app:latest


The container image reference is hardcoded with a specific project ID 'hpe-design-system-adoption'. This makes the configuration non-portable across different projects. Consider using the template version for better maintainability.

Suggested change

- image: gcr.io/hpe-design-system-adoption/pocketbase-app:latest

serviceAccountName: pocketbase-service-account@${PROJECT_ID}.iam.gserviceaccount.com

containers:

- image: gcr.io/${PROJECT_ID}/pocketbase-app:latest

Copilot · 2025-08-06T23:31:17Z

apps/pocketbase_app/cloud-run-service.yaml

+        csi:
+          driver: gcsfuse.run.googleapis.com
+          volumeAttributes:
+            bucketName: ds-pocketbase


The bucket name is hardcoded as 'ds-pocketbase'. This makes the configuration non-portable across different projects where the bucket name might need to be different. Consider using the template version for better maintainability.

Suggested change

bucketName: ds-pocketbase

bucketName: ${GCS_BUCKET_NAME}

Copilot · 2025-08-06T23:31:17Z

apps/pocketbase_app/Dockerfile

+  fi && \
+  echo "✅ Checksum verification passed" && \
+  unzip /tmp/pocketbase.zip -d /app && \
+  rm /tmp/pocketbase.zip /tmp/checksums.txt && \


The checksum verification assumes the checksum file uses space as delimiter and the hash is in the first field. However, different checksum formats may use different delimiters or field orders. Consider using sha256sum -c with a properly formatted checksums file for more robust verification.

Suggested change

rm /tmp/pocketbase.zip /tmp/checksums.txt && \

grep "pocketbase_${PB_VERSION}_linux_amd64.zip" /tmp/checksums.txt | \

sed "s/pocketbase_${PB_VERSION}_linux_amd64.zip$/\/tmp\/pocketbase.zip/" > /tmp/pb_checksum.txt && \

sha256sum -c /tmp/pb_checksum.txt && \

echo "✅ Checksum verification passed" && \

unzip /tmp/pocketbase.zip -d /app && \

rm /tmp/pocketbase.zip /tmp/checksums.txt /tmp/pb_checksum.txt && \

apps/pocketbase_app/DEPLOYMENT.md

Co-authored-by: Copilot <[email protected]>

Pocketbase Dockerfile and deployment documentation

458bc26

halocline requested a review from Copilot August 5, 2025 17:12

This comment was marked as outdated.

Sign in to view

halocline and others added 3 commits August 5, 2025 11:18

Update apps/pocketbase_app/startup.sh

350ec24

Co-authored-by: Copilot <[email protected]>

Update apps/pocketbase_app/Dockerfile

5a00e56

Co-authored-by: Copilot <[email protected]>

Update apps/pocketbase_app/README.md

c508cdf

Co-authored-by: Copilot <[email protected]>

halocline requested a review from Copilot August 5, 2025 17:20

This comment was marked as outdated.

Sign in to view

halocline and others added 7 commits August 5, 2025 11:51

Update apps/pocketbase_app/Dockerfile

a8deb93

Co-authored-by: Copilot <[email protected]>

Update apps/pocketbase_app/startup.sh

dec4696

Co-authored-by: Copilot <[email protected]>

Update apps/pocketbase_app/startup.sh

86a6fd8

Co-authored-by: Copilot <[email protected]>

Update apps/pocketbase_app/startup.sh

71ab1d2

Co-authored-by: Copilot <[email protected]>

revert startup script

048c46d

cleaning up startup script

0bbf9b0

Dockerfile security improvements

26f5a07

halocline requested a review from Copilot August 5, 2025 18:08

This comment was marked as outdated.

Sign in to view

halocline added 2 commits August 5, 2025 12:21

error handling

68fbc7d

Dockerfile enhancements

da56cd3

halocline requested a review from Copilot August 5, 2025 18:27

This comment was marked as outdated.

Sign in to view

halocline and others added 2 commits August 5, 2025 12:32

Update apps/pocketbase_app/README.md

d542472

Co-authored-by: Copilot <[email protected]>

final improvements

8e14cd5

halocline requested a review from Copilot August 5, 2025 18:37

This comment was marked as outdated.

Sign in to view

halocline requested review from britt6612 and taysea August 5, 2025 18:52

halocline requested a review from jcfilben August 5, 2025 18:52

fixed persistence issue

08a145c

halocline requested a review from Copilot August 6, 2025 23:01

This comment was marked as outdated.

Sign in to view

halocline added 2 commits August 6, 2025 17:19

make YAML portable

a93ba01

fixed typo

649ad1b

halocline requested a review from Copilot August 6, 2025 23:29

Copilot AI reviewed Aug 6, 2025

View reviewed changes

halocline and others added 2 commits August 6, 2025 17:59

Update apps/pocketbase_app/DEPLOYMENT.md

bc2b510

Co-authored-by: Copilot <[email protected]>

adjusting permissions

dcde538

	chmod 755 "$DATA_DIR" 2>/dev/null \|\| true
	chmod 700 "$DATA_DIR" 2>/dev/null \|\| true

	--role="roles/storage.admin"
	--role="roles/storage.objectAdmin"

	serviceAccountName: pocketbase-service-account@hpe-design-system-adoption.iam.gserviceaccount.com
	serviceAccountName: pocketbase-service-account@${PROJECT_ID}.iam.gserviceaccount.com

-  rm /tmp/pocketbase.zip /tmp/checksums.txt && \
+  grep "pocketbase_${PB_VERSION}_linux_amd64.zip" /tmp/checksums.txt | \
+  sed "s/pocketbase_${PB_VERSION}_linux_amd64.zip$/\/tmp\/pocketbase.zip/" > /tmp/pb_checksum.txt && \
+  sha256sum -c /tmp/pb_checksum.txt && \
+  echo "✅ Checksum verification passed" && \
+  unzip /tmp/pocketbase.zip -d /app && \
+  rm /tmp/pocketbase.zip /tmp/checksums.txt /tmp/pb_checksum.txt && \

Pocketbase Dockerfile and deployment documentation #5253

Are you sure you want to change the base?

Pocketbase Dockerfile and deployment documentation #5253

Uh oh!

Conversation

halocline commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

PR detail

Uh oh!

changeset-bot bot commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

netlify bot commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for hpe-theme-preview ready!

Uh oh!

netlify bot commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for unrivaled-bublanina-3a9bae ready!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

halocline commented Aug 5, 2025 •

edited

Loading

changeset-bot bot commented Aug 5, 2025 •

edited

Loading

netlify bot commented Aug 5, 2025 •

edited

Loading

netlify bot commented Aug 5, 2025 •

edited

Loading