diff --git a/back/Dockerfile b/back/Dockerfile new file mode 100644 index 00000000..b0218260 --- /dev/null +++ b/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"] diff --git a/back/docs/developer_guide/code_style.md b/back/docs/developer_guide/code_style.md new file mode 100644 index 00000000..bb065c83 --- /dev/null +++ b/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. diff --git a/back/docs/developer_guide/quickstart.md b/back/docs/developer_guide/quickstart.md index e38aeb65..8229dba5 100644 --- a/back/docs/developer_guide/quickstart.md +++ b/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 + ``` diff --git a/back/mkdocs.yml b/back/mkdocs.yml index 5fea0992..05bb1d50 100644 --- a/back/mkdocs.yml +++ b/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: diff --git a/back/src/whombat/system/database.py b/back/src/whombat/system/database.py index 4ed86135..2d1da0e5 100644 --- a/back/src/whombat/system/database.py +++ b/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, diff --git a/back/uv.lock b/back/uv.lock index e50b8ac4..511f9fd2 100644 --- a/back/uv.lock +++ b/back/uv.lock @@ -2369,7 +2369,7 @@ wheels = [ [[package]] name = "whombat" -version = "0.6.2" +version = "0.6.3" source = { editable = "." } dependencies = [ { name = "aiosqlite", marker = "python_full_version >= '3.12' and python_full_version < '4'" }, diff --git a/compose-dev.yaml b/compose-dev.yaml new file mode 100644 index 00000000..d2ea0405 --- /dev/null +++ b/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: diff --git a/front/Dockerfile b/front/Dockerfile new file mode 100644 index 00000000..8637280e --- /dev/null +++ b/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" ]