Merge pull request #34 from mbsantiago/feat/development-docker-compose

Feat/development docker compose

back/Dockerfile

@@ -0,0 +1,27 @@
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+WORKDIR /code
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-project --dev
+
+ADD . /code
+
+RUN mkdir /audio
+RUN mkdir /data
+
+VOLUME ["/data"]
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
+
+ENV WHOMBAT_AUDIO_DIR /audio
+ENV WHOMBAT_HOST="0.0.0.0"
+ENV WHOMBAT_DOMAIN="localhost"
+ENV WHOMBAT_DB_URL="sqlite+aiosqlite:////data/whombat.db"
+ENV PATH="/code/.venv/bin:$PATH"
+
+# Run the command to start the web server
+CMD ["whombat"]

back/docs/developer_guide/code_style.md

@@ -0,0 +1,27 @@
+## Our Standards
+
+At Whombat, we emphasize code quality and employ various tools to streamline development.
+
+### Code Formatting
+
+We follow the black style for Python to maintain consistent formatting throughout the project.
+Additionally, we use isort to organize imports neatly.
+For the Typescript project, prettier serves as the primary code formatter.
+
+### Linting
+
+We utilize the following tools for linting and error checking:
+
+1. Python:
+
+   - **Ruff** for fast overall error checking
+   - **Pyright** for type checking
+
+2. Typescript:
+   - **Eslint** for linting
+   - **Tsc** for checking Typescript code
+
+### Documentation
+
+We adhere to the Numpy docstring format for documenting Python code.
+Our documentation is built using mkdocs, providing a clear and organized structure for users and contributors.

back/docs/developer_guide/quickstart.md

@@ -1,10 +1,29 @@
 # Quickstart
 
-## Pre-requisites
+While developing, it's often helpful to run development servers that host different parts of the application, or provide specific views, such as the UI components or documentation.
+
+These development servers include:
+
+- **FastAPI Backend Server**: Hosts the Python API.
+- **Next.js Frontend Server**: Builds and serves the user interface.
+- **Storybook Server**: Allows you to browse and visually inspect all UI components.
+- **MkDocs Server**: Renders and serves the project documentation.
+
+This guide will show you how to start these servers, allowing you to see how your code changes are reflected in the app in real time.
+
+This guide provides two ways to set up your _Whombat_ development environment:
+
+**Manual Setup**: Ideal if you prefer direct control over your development environment and are comfortable managing dependencies.
+
+**Docker Compose**: Streamlines setup and provides a consistent environment.
+
+## Option 1: Manual Setup
+
+### Pre-requisites
 
 Before setting up your Whombat development environment, ensure you have the following tools installed:
 
-1. **Python 3.12**: We developed Whombat using this version, but any newer version should be compatible.
+1. **Python 3.12**: We developed Whombat using this version, but any version greater or equal to 3.11 should be compatible.
       Download Python 3.12 [here](https://www.python.org/downloads/release/python-3117/).
 
 2. **uv**: UV is a Python package dependency manager that we use to manage dependencies for the Python part of Whombat.
@@ -13,7 +32,7 @@ Before setting up your Whombat development environment, ensure you have the foll
 3. **Node.js**: We use Node.js to develop and bundle the final JavaScript code for the Whombat frontend.
       Download the latest version [here](https://nodejs.org/dist/v20.11.0/node-v20.11.0-linux-x64.tar.xz).
 
-## Set Up a Development Environment
+### Set Up
 
 After confirming that you have all the prerequisites ready, follow these steps to set up a development environment on your machine.
 
@@ -27,7 +46,7 @@ git clone https://github.com/mbsantiago/whombat.git
 
 ```bash
 cd whombat/back
-uv sync
+uv sync --dev
 ```
 
 3. Move to the frontend directory and install all dependencies:
@@ -39,47 +58,87 @@ npm install
 
 These instructions ensure you have the necessary tools and dependencies to kickstart Whombat development on your local machine.
 
-## Running the Development Server
+### Running the Development Servers
 
-Once installed, you can start the backend server by navigating to the `back` directory and running:
+- **Backend**: To initiate the backend server, run the following command from the project's root directory:
 
 ```bash
-make serve-dev
+make serve-back
 ```
 
-You can also start the frontend development server by navigating to the `front` directory and running:
+- **Frontend**: To start the frontend development server, run:
+
+```bash
+make serve-front
+```
+
+Once both servers are running, navigate to [http://localhost:3000](http://localhost:3000) in your web browser to access the Whombat development environment.
+
+- **Storybook:**
+
+  ```bash
+  make storybook
+  ```
+
+  Access Storybook at http://localhost:6006.
+
+- **Documentation Server:**
+
+  ```bash
+  make dev-docs
+  ```
+
+  View the documentation at http://localhost:8000.
+
+## Option 2: Docker Compose
+
+### Pre-requisites
+
+- **Docker** and **Docker Compose**: Install them by following the instructions for your operating system on the official Docker [website](https://docs.docker.com/compose/install/).
+
+### Set Up
+
+Once you have Docker Compose installed, follow these steps:
+
+1. Clone the Repository
 
 ```bash
-npm run dev
+git clone https://github.com/mbsantiago/whombat.git
 ```
 
-These commands initiate the development servers for both the backend and frontend components of Whombat.
-Navigate to [localhost:3000](localhost:3000) to access the development front end.
+2. Navigate to the Project Directory
+
+```bash
+cd whombat
+```
 
-## Our Standards
+### Run Services
 
-At Whombat, we emphasize code quality and employ various tools to streamline development.
+- **Backend and Frontend:**
 
-### Code Formatting
+  ```bash
+  docker-compose -f compose-dev.yaml up backend frontend
+  ```
 
-We follow the black style for Python to maintain consistent formatting throughout the project.
-Additionally, we use isort to organize imports neatly.
-For the Typescript project, prettier serves as the primary code formatter.
+  Access the Whombat development environment at http://localhost:3000
 
-### Linting
+- **Storybook:**
 
-We utilize the following tools for linting and error checking:
+  ```bash
+  docker-compose -f compose-dev.yaml up storybook
+  ```
 
-1. Python:
+  Access Storybook at http://localhost:6006.
 
-   - **Ruff** for fast overall error checking
-   - **Pyright** for type checking
+- **Documentation Server:**
 
-2. Typescript:
-   - **Eslint** for linting
-   - **Tsc** for checking Typescript code
+  ```bash
+  docker-compose -f compose-dev.yaml up docs
+  ```
 
-### Documentation
+  View the documentation at http://localhost:8000.
 
-We adhere to the Numpy docstring format for documenting Python code.
-Our documentation is built using mkdocs, providing a clear and organized structure for users and contributors.
+- **All Services:**
+  ```bash
+  docker-compose -f compose-dev.yaml up
+  ```

back/mkdocs.yml

@@ -14,12 +14,12 @@ nav:
   - Developer Guide:
       - developer_guide/index.md
       - Quickstart: developer_guide/quickstart.md
-      - Architecture: developer_guide/architecture.md
-      - Database Layer: developer_guide/database.md
-      - Python API: developer_guide/api.md
-      - HTTP REST API: developer_guide/rest_api.md
-      - Front End: developer_guide/front_end.md
-      - Plugins: developer_guide/plugins.md
+      # - Architecture: developer_guide/architecture.md
+      # - Database Layer: developer_guide/database.md
+      # - Python API: developer_guide/api.md
+      # - HTTP REST API: developer_guide/rest_api.md
+      # - Front End: developer_guide/front_end.md
+      # - Plugins: developer_guide/plugins.md
       - Contributing: CONTRIBUTING.md
       - Code of Conduct: CODE_OF_CONDUCT.md
   - Reference:

back/src/whombat/system/database.py

@@ -100,15 +100,17 @@ def get_database_url(
     URL
         The database url.
     """
-    if settings.dev:
-        return make_url(
+    db_url = settings.db_url
+
+    if settings.dev and db_url is None:
+        db_url = (
             "sqlite+aiosqlite:///whombat.db"
             if is_async
             else "sqlite:///whombat.db"
         )
 
-    if settings.db_url:
-        return make_url(settings.db_url)
+    if db_url:
+        return make_url(db_url)
 
     url = URL.create(
         drivername=settings.db_dialect,

compose-dev.yaml

@@ -0,0 +1,78 @@
+services:
+  backend:
+    build:
+      context: back
+    container_name: whombat-backend
+    command: ["uv", "run", "whombat"]
+    environment:
+      - WHOMBAT_DEV=true
+      - WHOMBAT_DATA_DIR=/data/
+      - WHOMBAT_DB_URL=sqlite+aiosqlite:////data/whombat.db
+    networks:
+      - public
+    volumes:
+      - type: volume
+        source: db-data
+        target: /data
+      - type: bind
+        source: example_data/audio
+        target: /audio
+    ports:
+      - 5000:5000
+    develop:
+      watch:
+        - action: sync
+          path: back/src
+          target: /code/src
+  frontend:
+    build:
+      context: front
+      args:
+        - NODE_ENV=development
+    container_name: whombat-frontend
+    command: ["npm", "run", "dev"]
+    depends_on:
+      - backend
+    networks:
+      - public
+    ports:
+      - 3000:3000
+    develop:
+      watch:
+        - action: sync
+          path: front
+          target: /code
+  storybook:
+    build:
+      context: front
+      args:
+        - NODE_ENV=development
+    container_name: whombat-storybook
+    command: ["npm", "run", "storybook"]
+    ports:
+      - 6006:6006
+    develop:
+      watch:
+        - action: sync
+          path: front
+          target: /code
+  docs:
+    build:
+      context: back
+    container_name: whombat-docs
+    ports:
+      - 8000:8000
+    command: ["uv", "run", "mkdocs", "serve", "-a", "0.0.0.0:8000"]
+    develop:
+      watch:
+        - action: sync
+          path: back/docs
+          target: /code/docs
+        - action: sync
+          path: back/mkdocs.yml
+          target: /code/mkdocs.yml
+
+networks:
+  public:
+volumes:
+  db-data:

front/Dockerfile

@@ -0,0 +1,16 @@
+FROM node:lts
+
+ENV CI=true
+ENV PORT=3000
+
+WORKDIR /code
+
+COPY package.json /code/package.json
+
+COPY package-lock.json /code/package-lock.json
+
+RUN npm ci
+
+COPY . /code
+
+CMD [ "npm", "run", "dev" ]