scaffold-deply/Design_Doc/Operations.md

Project Name - Operations Guide

Quick Start

Step 1: First Time Setup

When no configuration file exists, the script will setup a new instance with an interactive wizard:

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

The wizard will ask you:

1. Instance Name: Name for the Docker container (default: my-app)
2. Image Configuration: Docker image name and tag
3. Volume Mappings: Where to store persistent data
4. Debug Mode: Enable verbose logging (optional)

What Happens:

• Creates .env with your settings
• Creates temporary build context (.app-build/)
• Builds Docker image locally from embedded Dockerfile
• Creates and starts the container
• Cleans up build context immediately
• Validates the deployment

Configuration File Created:

• .env — Application instance configuration

Note: The Docker image is built locally — no external image pull required. The build context is deleted immediately after the build completes.

Deployment Complete Output

After successful deployment, you'll see a summary like this:

============================================
  Deployment Complete! Container Operation Commands

  Re-Run Container:
    - Prepare your `.env`
    - curl -s "<URL>/deploy-project.sh" | bash
  ------------------------------------------------------------
  Container Accessing:
    docker exec -it -u root my-app bash
    docker exec -it -u node my-app bash
  ------------------------------------------------------------
  View the Logs: docker logs --tail 50 my-app
  ------------------------------------------------------------
  Inspect: docker inspect my-app
  ------------------------------------------------------------
  Remove Container: docker rm -f my-app
  ------------------------------------------------------------
  Remove Volumes (if needed):
    docker volume rm my-app_data-vol my-app_config-vol
============================================

Note:

• Volume names use the format ${INSTANCE_NAME}_data-vol and ${INSTANCE_NAME}_config-vol for easy identification. The script automatically lists all volumes associated with your instance.
• Container Accessing: You can access the container as either root user (full privileges) or node user (non-root, limited privileges). Use root for administrative tasks and node for regular application operations.

Step 2: Using Existing Configuration

If you already have a .env file, simply run:

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

The script will:

• Load settings from .env
• Rebuild the Docker image (if needed)
• Recreate the container with current settings
• Preserve all persistent data in Docker volumes

Alternative: Manual Configuration

1. Create .env file manually:

   cat > .env << EOF
   INSTANCE_NAME="my-app"
   IMAGE_NAME="my-app"
   IMAGE_TAG="latest"
   EOF
   

2. Run the deployment script:

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

Common Operations

Access the Container

The container runs with tail -f /dev/null, so you need to exec in to run commands:

docker exec -it <instance-name> bash

Once inside, you can:

• Run your application manually
• Inspect the filesystem
• Debug issues
• Run one-off commands

Check Status

docker ps | grep <instance-name>

View Logs

docker logs -f <instance-name>

Stop Container

docker stop <instance-name>

Start Container

docker start <instance-name>

Remove Container

docker rm -f <instance-name>

Redeploy

# Remove old container and run script again
docker rm -f <instance-name>
curl -s "<URL>/deploy-project.sh" | bash

Access Persistent Data

Data is stored in Docker volumes. To access:

# List volumes
docker volume ls | grep <instance-name>

# Inspect a volume
docker volume inspect <instance-name>_data-vol

# Run a container to access volume contents
docker run --rm -v <instance-name>_data-vol:/data alpine ls -la /data

Troubleshooting

Container Won't Start

Check logs:

docker logs <instance-name>

Verify Docker is running:

docker ps

Check for port conflicts:

docker port <instance-name>

Build Fails

Check Docker daemon:

systemctl status docker

Verify disk space:

df -h

Clean up old images:

docker image prune -f

Volume Permission Issues

Inspect volume:

docker volume inspect <instance-name>_data-vol

Create a test container to fix permissions:

docker run --rm -v <instance-name>_data-vol:/data alpine chown -R 1000:1000 /data

Network Issues

List networks:

docker network ls

Inspect network:

docker network inspect <instance-name>_internal-net

Recreate network:

docker network rm <instance-name>_internal-net
docker network create <instance-name>_internal-net

Reset to Fresh State

# Stop and remove container
docker rm -f <instance-name>

# Remove volumes (WARNING: deletes all data!)
docker volume rm <instance-name>_data-vol <instance-name>_config-vol

# Remove network
docker network rm <instance-name>_internal-net

# Remove configuration
rm .env

# Remove image (optional)
docker rmi <image-name>:latest

# Run wizard again
curl -s "<URL>/deploy-project.sh" | bash

FAQ

Q: Where is my data stored? A: Data is stored in Docker volumes as specified in the VOLUMES array in .env. Volumes are auto-prefixed with the instance name.

Q: Why does the container run tail -f /dev/null? A: This is the ephemeral runtime policy. The container stays running without starting any application automatically. You exec in to run commands manually, giving you full control.

Q: Can I run multiple instances? A: Yes, use different INSTANCE_NAME values for each instance. Each will have its own volumes and network.

Q: How do I update the application? A: Run the script again. It will rebuild the image and recreate the container with current settings.

Q: Is my configuration backed up? A: Yes, your .env file contains all configuration. Keep it safe!

Q: What happens to the .app-build folder? A: It's created temporarily during build and deleted immediately after the image is built. This is the ephemeral runtime policy in action.

Q: Can I customize the Dockerfile? A: Yes, modify the embedded Dockerfile in the create_build_context() function in the deploy script.

Best Practices

1. Always keep .env backed up — It contains all your configuration
2. Use meaningful instance names — Helps when managing multiple instances
3. Review logs regularly — Catch issues early
4. Document custom settings — Add comments in .env for future reference
5. Clean up unused volumes — Periodically remove orphaned volumes
6. Exec in for application commands — Remember, the container doesn't start your app automatically