env-ubuntu

A ready-to-use Ubuntu development environment with MySQL, plus optional GUI app support on macOS (Apple Silicon or Intel). It ships with simple scripts to start, backup, and restore your environment reproducibly.

---

Features

• 🐧 Ubuntu 22.04 amd64 container
• 🗄️ MySQL 8.0 with persistent storage
• 🔁 One-command backup (image + tar) and restore
• 🖥️ GUI app support on macOS via XQuartz
• 📂 Host folder ./shared mapped to /home/<username>/shared inside the container

---

Prerequisites

• Docker Desktop installed and running

  • Download: https://www.docker.com/products/docker-desktop

• macOS only (for GUI apps): Install XQuartz

  • Open XQuartz → Preferences → Security, enable Allow connections from network clients

  • In a macOS terminal (outside the container) run once:

    xhost + 127.0.0.1

---

Quick Start

./start.sh

• On first run, you’ll be asked for your Ubuntu username and password.
• The script will start the Ubuntu and MySQL containers.
• A host folder ./shared is mounted into the container at /home/<your_username>/shared.
• You’ll be attached as the created user to an interactive login shell inside the container.

---

start.sh — Options & Examples

./start.sh [options]

Options

• No args — start/attach to the environment; prompt on first run.

• --recreate — forcefully recreate the Ubuntu container from the current image (no pull/build).

• --restore <backup.tar> — restore from a backup tar produced by backup.sh.

  ./start.sh --restore backups/env-ubuntu-backup-20250912-143000.tar

• --restore <image:tag> — restore from a local image tag (also produced by backup.sh).

  ./start.sh --restore env-ubuntu:backup-20250912-143000

• -h, --help — show usage.

Under the hood, --restore retags your backup to env-ubuntu:latest and recreates without building so your restored filesystem isn’t overwritten.

---

Accessing MySQL (inside the Ubuntu container)

mysql -h mysql-server -P 3306 -u root -p

Defaults (from compose.yml):

• Root password: db
• Also provisioned: database db, user db, password db

---

Running GUI Apps (macOS)

1. Ensure XQuartz is installed and running.

2. In XQuartz: Preferences → Security → Allow connections from network clients.

3. In macOS terminal (once):

   xhost + 127.0.0.1

4. Inside the Ubuntu container try:

   xeyes

   (or xclock, etc.)

---

Backups

Create a backup (image + tar):

./backup.sh

This will:

• Commit the current container filesystem to an image: env-ubuntu-backup:<timestamp>

• Also tag a convenience image: env-ubuntu:backup-<timestamp>

• Save a tar file under ./backups/, e.g.:

  backups/env-ubuntu-backup-20250912-143000.tar
  

backup.sh — Options

• No args — create a timestamped backup (image + tar).

• --name <suffix> — custom suffix instead of timestamp.

  ./backup.sh --name myproject

  Produces:

  backups/env-ubuntu-backup-myproject.tar
  image tag: env-ubuntu:backup-myproject
  

Restoring

• From tar:

  ./start.sh --restore backups/env-ubuntu-backup-20250912-143000.tar

• From image tag:

  ./start.sh --restore env-ubuntu:backup-20250912-143000

---

Environment Variables (.env)

Created automatically on first run (or you can edit manually):

USER_NAME=<your_username>
USER_UID=1000
USER_GID=1000
HOST_DATA_PATH=./shared
CONTAINER_DATA_DIR=/home/<your_username>/shared
USER_PASSWORD=<your_password>

USER_PASSWORD is stored in plaintext in .env (by design here). If you want a safer approach, switch to Docker secrets and remove this line.

---

Project Structure

.
├─ compose.yml
├─ Dockerfile
├─ entrypoint.sh
├─ start.sh
├─ backup.sh
├─ .env                 # auto-created on first run
├─ shared/              # host<->container shared folder
└─ backups/             # backup tars (from backup.sh)

---

Troubleshooting

• WARN: The "USER_PASSWORD" variable is not set Ensure .env contains a line:

  USER_PASSWORD=yourpassword
  

  Then re-run ./start.sh.

• service "mysql" refers to undefined volume ... If you changed the volume name under services.mysql.volumes, also define it at the bottom under volumes: (names must match).

• Restoring doesn’t seem to apply Use ./start.sh --restore <backup.tar|image:tag>. The script retags to env-ubuntu:latest and recreates with --no-build --pull=never to avoid clobbering the restored filesystem.

• Entering as root / no colors start.sh attaches as your created user with colored prompt/ls. If you still see no colors, ensure you’re attached with bash -il (the script already does this).

• Validate Docker Compose config

  docker compose -f compose.yml config

---

License

This project is provided as-is, without warranty. Use at your own risk.