282 lines
6.9 KiB
Markdown
282 lines
6.9 KiB
Markdown
# 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
|