chungyan5 fce315675a init. & setup this scaffold for coming other app deployment scripts, it is a good reference and starting point

2026-03-13 16:20:42 +00:00

6.4 KiB

Raw Blame History

Project Name - Specifications

Welcome

This document explains what the deployment system does and what you need to run it. Think of this as a friendly guide to understand the features and requirements before you start.

What Does This System Do?

The deployment script (deploy-project.sh) helps you set up a Docker-based application on your Linux computer. It's designed to be simple and smart — it automatically detects your situation and guides you through the right steps.

Smart Setup — Four Scenarios

The script handles four different situations automatically:

Do you have a `.env` file?	Do you have a running container?	What the script does
No	No	Sets up a new instance with helpful questions
Yes	No	Sets up using your saved settings
No	Yes	Helps you reconfigure with new settings
Yes	Yes	Refreshes your existing setup

What is the .env file? It's a simple configuration file that stores your settings so you don't have to enter them every time.

What's Included

Smart Setup — Detects your situation and does the right thing automatically
Interactive Questions — First-time setup asks you what you need
Persistent Settings — Your configuration is saved for next time
Clean Operation — No files left on your system except what you need
Ephemeral Runtime — Docker image built locally from embedded Dockerfile
Manual Exec Mode — Container runs with tail -f /dev/null for on-demand access

Ephemeral Runtime Policy

This system follows a clean, ephemeral runtime approach:

What Is Ephemeral Runtime?

Local Image Build — Docker image is built from an embedded Dockerfile in the script
No External Dependencies — No need to pull images from Docker Hub or other registries
Temporary Build Context — Build files are created only during setup, then immediately deleted
Clean System — Your computer stays tidy with no leftover build files

How It Works

Script creates a temporary .app-build directory with a Dockerfile
Docker builds the image locally
Container is deployed with the new image
Build directory is immediately deleted
Only your .env configuration and Docker volumes remain

Container Runtime Mode

The container runs with tail -f /dev/null as its main process:

Container stays running indefinitely
No application starts automatically
You exec into the container manually to run commands
Perfect for interactive development and debugging

What You Need (System Requirements)

Minimum Requirements

Computer: Any Linux computer
Docker: Version 20.10 or newer
Bash: Version 4.0 or newer
Memory: At least 512 MB RAM
Storage: At least 1 GB free space

What Needs to Be Installed

What	Why	Required?
Docker Engine	Runs the container	Yes
Bash	Runs the script	Yes
curl	Downloads the script (optional)	No
git	Clones the repository (optional)	No

Key Features

One-Command Setup

Just run one command, and the script does everything for you:

Checks what you already have set up
Asks you questions if needed (first time only)
Builds Docker image locally
Creates and starts the container
Saves your settings for next time
Cleans up temporary files

Friendly Interactive Questions

If it's your first time, the script will ask you a few simple questions:

What would you like to name your instance? (default: my-app)
What Docker image name to use? (default: my-app)
What tag for the image? (default: latest)
How to configure volumes?
Enable debug mode?

The script uses your terminal directly, so the questions work even if you run the script from a downloaded link.

Clean and Tidy

The script follows a "leave no trace" policy:

Build context created only in .app-build directory during setup
Build context deleted immediately after image is built
Your important settings are stored safely in Docker volumes
After setup, your computer stays clean — only .env file remains

Keeps Your Work Safe

Your configuration is stored in Docker volumes that survive even if you restart or remove the container. This means:

Your data is preserved automatically
You can update or refresh without losing your configuration
Volumes are auto-created with instance-prefixed names

Helpful Error Messages

If something goes wrong, the script tells you clearly what happened and what to do about it. It also checks that Docker is installed and running before starting.

Configuration Settings

What Gets Saved

When you run the setup, your settings are saved to .env in the current directory:

Variable	Description	Default
`INSTANCE_NAME`	Name of the Docker container	`my-app`
`IMAGE_NAME`	Docker image name	`my-app`
`IMAGE_TAG`	Image version tag	`latest`
`VOLUMES`	Volume mappings (array)	varies
`NETWORKS`	Network connections (array)	varies
`DEBUG`	Enable verbose logging	`false`
`TZ`	Timezone	`UTC`

Volume Configuration

Volumes use a special naming convention:

_prefix — Auto-prefixed with instance name (e.g., _data-vol becomes my-app_data-vol)
Named volumes — Created automatically if not exists
Persistent — Survive container removal

Network Configuration

Networks follow the same pattern:

_prefix — Auto-prefixed with instance name
External networks — Use exact name, must exist beforehand

Usage Examples

First Time Setup

curl -s "<URL>/deploy-project.sh" | bash

The wizard will guide you through the setup.

Using Existing Configuration

curl -s "<URL>/deploy-project.sh" | bash

If .env exists, the script uses your saved settings.

Access the Container

docker exec -it my-app bash

View Logs

docker logs -f my-app

Stop Container

docker stop my-app

Remove and Redeploy

docker rm -f my-app
curl -s "<URL>/deploy-project.sh" | bash

6.4 KiB Raw Blame History