# 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:

```bash
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:

```bash
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:
   ```bash
   cat > .env << EOF
   INSTANCE_NAME="my-app"
   IMAGE_NAME="my-app"
   IMAGE_TAG="latest"
   EOF
   ```

2. Run the deployment script:
   ```bash
   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:

```bash
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

```bash
docker ps | grep <instance-name>
```

### View Logs

```bash
docker logs -f <instance-name>
```

### Stop Container

```bash
docker stop <instance-name>
```

### Start Container

```bash
docker start <instance-name>
```

### Remove Container

```bash
docker rm -f <instance-name>
```

### Redeploy

```bash
# 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:

```bash
# 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:**
```bash
docker logs <instance-name>
```

**Verify Docker is running:**
```bash
docker ps
```

**Check for port conflicts:**
```bash
docker port <instance-name>
```

### Build Fails

**Check Docker daemon:**
```bash
systemctl status docker
```

**Verify disk space:**
```bash
df -h
```

**Clean up old images:**
```bash
docker image prune -f
```

### Volume Permission Issues

**Inspect volume:**
```bash
docker volume inspect <instance-name>_data-vol
```

**Create a test container to fix permissions:**
```bash
docker run --rm -v <instance-name>_data-vol:/data alpine chown -R 1000:1000 /data
```

### Network Issues

**List networks:**
```bash
docker network ls
```

**Inspect network:**
```bash
docker network inspect <instance-name>_internal-net
```

**Recreate network:**
```bash
docker network rm <instance-name>_internal-net
docker network create <instance-name>_internal-net
```

### Reset to Fresh State

```bash
# 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