215 lines
6.4 KiB
Markdown
215 lines
6.4 KiB
Markdown
# 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
|
|
|
|
1. Script creates a temporary `.app-build` directory with a Dockerfile
|
|
2. Docker builds the image locally
|
|
3. Container is deployed with the new image
|
|
4. Build directory is immediately deleted
|
|
5. 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
|
|
|
|
### Recommended
|
|
|
|
- **Computer**: Ubuntu 20.04 or newer
|
|
- **Docker**: Latest version
|
|
- **Bash**: Version 5.0 or newer
|
|
- **Memory**: 1 GB RAM
|
|
- **Storage**: 2 GB free space
|
|
- **Internet**: Stable connection (for downloading base images)
|
|
|
|
### 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
|
|
|
|
```bash
|
|
curl -s "<URL>/deploy-project.sh" | bash
|
|
```
|
|
|
|
The wizard will guide you through the setup.
|
|
|
|
### Using Existing Configuration
|
|
|
|
```bash
|
|
curl -s "<URL>/deploy-project.sh" | bash
|
|
```
|
|
|
|
If `.env` exists, the script uses your saved settings.
|
|
|
|
### Access the Container
|
|
|
|
```bash
|
|
docker exec -it my-app bash
|
|
```
|
|
|
|
### View Logs
|
|
|
|
```bash
|
|
docker logs -f my-app
|
|
```
|
|
|
|
### Stop Container
|
|
|
|
```bash
|
|
docker stop my-app
|
|
```
|
|
|
|
### Remove and Redeploy
|
|
|
|
```bash
|
|
docker rm -f my-app
|
|
curl -s "<URL>/deploy-project.sh" | bash
|
|
```
|