WellLog Project

---

Overview

The WellLog project consists of:

• A Streamlit application for interacting with well log data

• A backend with SQLAlchemy models and database logic

• Alembic migrations for schema management

• A MySQL database

• Fully containerized setup via Docker Compose (recommended for all team members)

---

Project Structure

project-root/
├── app/
│   └── main.py
├── backend/
│   ├── database.py
│   ├── models.py
│   └── __init__.py
├── migrations/
│   ├── env.py
│   ├── alembic.ini
│   └── versions/
├── requirements.txt
├── docker-compose.yml
├── Dockerfile
├── .gitignore
└── README.md

---

Running the Project with Docker (Easiest Method)

No MySQL installation required. No virtual environment required.

Requirements

• Install Docker Desktop:

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

Start the project

Run this from the project root:

docker compose up --build

Docker will:

1. Start a MySQL database container

2. Wait for MySQL to become ready

3. Run Alembic migrations automatically

4. Start the Streamlit app on http://localhost:8501

Stop the project

docker compose down

Restart the app

docker compose restart app

This only restarts the Streamlit app container without affecting the database.

Persisting database data

MySQL data is stored in a Docker volume so nothing is lost when containers restart.

---

Running Without Docker (Optional)

Only use this method if you prefer managing everything manually.

Requirements

• Python 3.11.2 (developed using this version, other versions might work too)

• MySQL running locally

• A virtual environment

Setup

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Set your local DATABASE_URL in backend/database.py:

mysql+pymysql://root@localhost/well_log_db

Initialize the database:

alembic upgrade head

Run the app:

streamlit run app/main.py

---

Database Migrations

Alembic migrations are used to create and modify the database schema.

Generating a migration

alembic revision --autogenerate -m "description"

Applying migrations

alembic upgrade head

If using Docker, migrations run automatically.

---

Environment Variables

The app and Alembic use a unified DATABASE_URL variable.

Inside Docker

DATABASE_URL=mysql+pymysql://root:root@db/well_log_db

This is set automatically by docker-compose.yml.

Outside Docker

Set it in your shell:

export DATABASE_URL="mysql+pymysql://root@localhost/well_log_db"

---

Troubleshooting

MySQL is not connecting

• If running manually, ensure the MySQL server is running

• Docker resolves this automatically

Alembic cannot find models

Ensure migrations/env.py includes:

from backend.models import Base
target_metadata = Base.metadata

Streamlit cannot connect to backend

Check that DATABASE_URL is correctly set.

---

Team Workflow

Commit rules

• Do not commit:

  • venv/

  • pycache/

  • MySQL data files

• Do commit:

  • migrations/ directory and migration scripts

  • All Python source files

  • Docker configuration files

Branch workflow

1. Create a branch for a feature

2. Make changes

3. Run the project with docker compose up

4. Submit a pull request