#Container Deployment Guide

This guide provides a complete workflow for building the multi-store application, packaging it into a minimal container image with Podman, and distributing it via AWS S3 for local execution.

#1. Overview

The goal is to create a self-contained, portable, and efficient artifact of the multi-store server. This allows any user (with credentials) to run the full application locally without needing to set up a full development environment.

The process is as follows:

1. Build: A multi-stage Dockerfile builds the Next.js standalone server inside a container to ensure consistency.
2. Package: The final output is a minimal container image.
3. Distribute: A script uploads a compressed version of this image to a private AWS S3 bucket.
4. Run: Another script downloads and runs the container locally, passing in the necessary environment variables.

#2. Architecture Diagram

graph TD
    subgraph Dev[Developer Machine]
        A[Repo Source Code] --> B[scripts build-image]
        B --> C[Multi-store Dockerfile]
        C --> D[Podman Image v1.0.7]
        D --> E[scripts upload-image]
    end

    subgraph Cloud[AWS Cloud]
        F[S3 Bucket]
    end

    subgraph User[User Machine]
        G[Podman Installed] --> H[scripts run-container]
        H --> F
        H --> I[Running App Container]
    end

    E --> F

    style B fill:#cde,stroke:#333,stroke-width:2px
    style E fill:#cde,stroke:#333,stroke-width:2px
    style H fill:#cde,stroke:#333,stroke-width:2px

#3. Prerequisites

Before you begin, ensure you have the following installed and configured on your system.

#All Operating Systems:

• Podman: The primary container engine. (Installation Guide)
  • Note for macOS/Windows: Podman typically requires a VM (like podman machine init).
• Node.js & Bun: Required for running build scripts and the uploader.
• AWS CLI: Required for uploading to S3. Configure it with your credentials (aws configure).

#Environment File:

• Create a .env file in the root of this repository.
• This file must contain all required environment variables for the multi-store application to run.
• A scripts/check-env.sh script is provided to help validate this file.
• Example .env content:

  # Payload
  PAYLOAD_SECRET=YOUR_SUPER_SECRET_KEY
  DATABASE_URI=mongodb://user:pass@host:port/db
  # NextAuth
  NEXTAUTH_SECRET=YOUR_NEXTAUTH_SECRET
  # ... other variables
  

#4. The Scripts

All scripts are located in the /scripts directory.

scripts/check-env.sh

• Purpose: Verifies that the root .env file exists and contains a minimal set of required keys.
• Usage: bash scripts/check-env.sh
• This is run automatically by the build script.

scripts/build-image.sh

• Purpose: Builds the multi-store container image using Podman.
• Usage: bash scripts/build-image.sh <version_tag>
• Example: bash scripts/build-image.sh v1.0.7
• This will create a tagged image: localhost/multi-store:v1.0.7.

scripts/upload-image.sh

• Purpose: Compresses the built image and uploads it to AWS S3.
• Usage: bash scripts/upload-image.sh <version_tag> <s3_bucket_name>
• Example: bash scripts/upload-image.sh v1.0.7 my-app-images
• This script runs the underlying upload-image.ts TypeScript file.

scripts/run-container.sh

• Purpose: Runs the specified version of the application container locally.
• Usage: bash scripts/run-container.sh <version_tag> [port]
• Example: bash scripts/run-container.sh v1.0.7 8080
• This will run the localhost/multi-store:v1.0.7 image and map the container's port 3000 to your local port 8080. If no port is specified, it defaults to 3000.
• It automatically passes the root .env file to the container.

#5. Full Workflow Example

Here is how you would perform a full build and release:

1. Ensure .env is correct.

   # Run the check manually if you want
   bash scripts/check-env.sh
   

2. Build the image with a new version tag.

   # Let's say the new version is 1.0.8
   bash scripts/build-image.sh v1.0.8
   

3. Upload the new image to your S3 bucket.

   bash scripts/upload-image.sh v1.0.8 my-flash-cms-images
   

4. (On another machine) Run the application.

   • First, ensure the .env file is also present on the user machine.
   • The user would need to download the image (or have it pre-loaded). For now, we assume they have access to the built image. A future script could handle the download-and-run logic.

   # Run the container, exposing it on port 4000
   bash scripts/run-container.sh v1.0.8 4000
   

   You can now access the application at http://localhost:4000.