Skip to content

Commit 8f65d75

Browse files
mbsantiagombsantiago
authored
Merge pull request #34 from mbsantiago/feat/development-docker-compose
Feat/development docker compose
2 parents e5955c6 + 7e62806 commit 8f65d75

File tree

8 files changed

+248
-39
lines changed

8 files changed

+248
-39
lines changed

‎back/Dockerfile

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
2+
3+
WORKDIR /code
4+
5+
RUN --mount=type=cache,target=/root/.cache/uv \
6+
--mount=type=bind,source=uv.lock,target=uv.lock \
7+
--mount=type=bind,source=pyproject.toml,target=pyproject.toml \
8+
uv sync --frozen --no-install-project --dev
9+
10+
ADD . /code
11+
12+
RUN mkdir /audio
13+
RUN mkdir /data
14+
15+
VOLUME ["/data"]
16+
17+
RUN --mount=type=cache,target=/root/.cache/uv \
18+
uv sync --frozen --no-dev
19+
20+
ENV WHOMBAT_AUDIO_DIR /audio
21+
ENV WHOMBAT_HOST="0.0.0.0"
22+
ENV WHOMBAT_DOMAIN="localhost"
23+
ENV WHOMBAT_DB_URL="sqlite+aiosqlite:////data/whombat.db"
24+
ENV PATH="/code/.venv/bin:$PATH"
25+
26+
# Run the command to start the web server
27+
CMD ["whombat"]

‎back/docs/developer_guide/code_style.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
## Our Standards
2+
3+
At Whombat, we emphasize code quality and employ various tools to streamline development.
4+
5+
### Code Formatting
6+
7+
We follow the black style for Python to maintain consistent formatting throughout the project.
8+
Additionally, we use isort to organize imports neatly.
9+
For the Typescript project, prettier serves as the primary code formatter.
10+
11+
### Linting
12+
13+
We utilize the following tools for linting and error checking:
14+
15+
1. Python:
16+
17+
- **Ruff** for fast overall error checking
18+
- **Pyright** for type checking
19+
20+
2. Typescript:
21+
- **Eslint** for linting
22+
- **Tsc** for checking Typescript code
23+
24+
### Documentation
25+
26+
We adhere to the Numpy docstring format for documenting Python code.
27+
Our documentation is built using mkdocs, providing a clear and organized structure for users and contributors.

‎back/docs/developer_guide/quickstart.md

+87-28
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,29 @@
11
# Quickstart
22

3-
## Pre-requisites
3+
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.
4+
5+
These development servers include:
6+
7+
- **FastAPI Backend Server**: Hosts the Python API.
8+
- **Next.js Frontend Server**: Builds and serves the user interface.
9+
- **Storybook Server**: Allows you to browse and visually inspect all UI components.
10+
- **MkDocs Server**: Renders and serves the project documentation.
11+
12+
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.
13+
14+
This guide provides two ways to set up your _Whombat_ development environment:
15+
16+
**Manual Setup**: Ideal if you prefer direct control over your development environment and are comfortable managing dependencies.
17+
18+
**Docker Compose**: Streamlines setup and provides a consistent environment.
19+
20+
## Option 1: Manual Setup
21+
22+
### Pre-requisites
423

524
Before setting up your Whombat development environment, ensure you have the following tools installed:
625

7-
1. **Python 3.12**: We developed Whombat using this version, but any newer version should be compatible.
26+
1. **Python 3.12**: We developed Whombat using this version, but any version greater or equal to 3.11 should be compatible.
827
Download Python 3.12 [here](https://www.python.org/downloads/release/python-3117/).
928

1029
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
1332
3. **Node.js**: We use Node.js to develop and bundle the final JavaScript code for the Whombat frontend.
1433
Download the latest version [here](https://nodejs.org/dist/v20.11.0/node-v20.11.0-linux-x64.tar.xz).
1534

16-
## Set Up a Development Environment
35+
### Set Up
1736

1837
After confirming that you have all the prerequisites ready, follow these steps to set up a development environment on your machine.
1938

@@ -27,7 +46,7 @@ git clone https://github.com/mbsantiago/whombat.git
2746

2847
```bash
2948
cd whombat/back
30-
uv sync
49+
uv sync --dev
3150
```
3251

3352
3. Move to the frontend directory and install all dependencies:
@@ -39,47 +58,87 @@ npm install
3958

4059
These instructions ensure you have the necessary tools and dependencies to kickstart Whombat development on your local machine.
4160

42-
## Running the Development Server
61+
### Running the Development Servers
4362

44-
Once installed, you can start the backend server by navigating to the `back` directory and running:
63+
- **Backend**: To initiate the backend server, run the following command from the project's root directory:
4564

4665
```bash
47-
make serve-dev
66+
make serve-back
4867
```
4968

50-
You can also start the frontend development server by navigating to the `front` directory and running:
69+
- **Frontend**: To start the frontend development server, run:
70+
71+
```bash
72+
make serve-front
73+
```
74+
75+
Once both servers are running, navigate to [http://localhost:3000](http://localhost:3000) in your web browser to access the Whombat development environment.
76+
77+
- **Storybook:**
78+
79+
```bash
80+
make storybook
81+
```
82+
83+
Access Storybook at http://localhost:6006.
84+
85+
- **Documentation Server:**
86+
87+
```bash
88+
make dev-docs
89+
```
90+
91+
View the documentation at http://localhost:8000.
92+
93+
## Option 2: Docker Compose
94+
95+
### Pre-requisites
96+
97+
- **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/).
98+
99+
### Set Up
100+
101+
Once you have Docker Compose installed, follow these steps:
102+
103+
1. Clone the Repository
51104

52105
```bash
53-
npm run dev
106+
git clone https://github.com/mbsantiago/whombat.git
54107
```
55108

56-
These commands initiate the development servers for both the backend and frontend components of Whombat.
57-
Navigate to [localhost:3000](localhost:3000) to access the development front end.
109+
2. Navigate to the Project Directory
110+
111+
```bash
112+
cd whombat
113+
```
58114

59-
## Our Standards
115+
### Run Services
60116

61-
At Whombat, we emphasize code quality and employ various tools to streamline development.
117+
- **Backend and Frontend:**
62118

63-
### Code Formatting
119+
```bash
120+
docker-compose -f compose-dev.yaml up backend frontend
121+
```
64122

65-
We follow the black style for Python to maintain consistent formatting throughout the project.
66-
Additionally, we use isort to organize imports neatly.
67-
For the Typescript project, prettier serves as the primary code formatter.
123+
Access the Whombat development environment at http://localhost:3000
68124

69-
### Linting
125+
- **Storybook:**
70126

71-
We utilize the following tools for linting and error checking:
127+
```bash
128+
docker-compose -f compose-dev.yaml up storybook
129+
```
72130

73-
1. Python:
131+
Access Storybook at http://localhost:6006.
74132

75-
- **Ruff** for fast overall error checking
76-
- **Pyright** for type checking
133+
- **Documentation Server:**
77134

78-
2. Typescript:
79-
- **Eslint** for linting
80-
- **Tsc** for checking Typescript code
135+
```bash
136+
docker-compose -f compose-dev.yaml up docs
137+
```
81138

82-
### Documentation
139+
View the documentation at http://localhost:8000.
83140

84-
We adhere to the Numpy docstring format for documenting Python code.
85-
Our documentation is built using mkdocs, providing a clear and organized structure for users and contributors.
141+
- **All Services:**
142+
```bash
143+
docker-compose -f compose-dev.yaml up
144+
```

‎back/mkdocs.yml

+6-6
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,12 @@ nav:
1414
- Developer Guide:
1515
- developer_guide/index.md
1616
- Quickstart: developer_guide/quickstart.md
17-
- Architecture: developer_guide/architecture.md
18-
- Database Layer: developer_guide/database.md
19-
- Python API: developer_guide/api.md
20-
- HTTP REST API: developer_guide/rest_api.md
21-
- Front End: developer_guide/front_end.md
22-
- Plugins: developer_guide/plugins.md
17+
# - Architecture: developer_guide/architecture.md
18+
# - Database Layer: developer_guide/database.md
19+
# - Python API: developer_guide/api.md
20+
# - HTTP REST API: developer_guide/rest_api.md
21+
# - Front End: developer_guide/front_end.md
22+
# - Plugins: developer_guide/plugins.md
2323
- Contributing: CONTRIBUTING.md
2424
- Code of Conduct: CODE_OF_CONDUCT.md
2525
- Reference:

‎back/src/whombat/system/database.py

+6-4
Original file line numberDiff line numberDiff line change
@@ -100,15 +100,17 @@ def get_database_url(
100100
URL
101101
The database url.
102102
"""
103-
if settings.dev:
104-
return make_url(
103+
db_url = settings.db_url
104+
105+
if settings.dev and db_url is None:
106+
db_url = (
105107
"sqlite+aiosqlite:///whombat.db"
106108
if is_async
107109
else "sqlite:///whombat.db"
108110
)
109111

110-
if settings.db_url:
111-
return make_url(settings.db_url)
112+
if db_url:
113+
return make_url(db_url)
112114

113115
url = URL.create(
114116
drivername=settings.db_dialect,

‎back/uv.lock

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎compose-dev.yaml

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
services:
2+
backend:
3+
build:
4+
context: back
5+
container_name: whombat-backend
6+
command: ["uv", "run", "whombat"]
7+
environment:
8+
- WHOMBAT_DEV=true
9+
- WHOMBAT_DATA_DIR=/data/
10+
- WHOMBAT_DB_URL=sqlite+aiosqlite:////data/whombat.db
11+
networks:
12+
- public
13+
volumes:
14+
- type: volume
15+
source: db-data
16+
target: /data
17+
- type: bind
18+
source: example_data/audio
19+
target: /audio
20+
ports:
21+
- 5000:5000
22+
develop:
23+
watch:
24+
- action: sync
25+
path: back/src
26+
target: /code/src
27+
frontend:
28+
build:
29+
context: front
30+
args:
31+
- NODE_ENV=development
32+
container_name: whombat-frontend
33+
command: ["npm", "run", "dev"]
34+
depends_on:
35+
- backend
36+
networks:
37+
- public
38+
ports:
39+
- 3000:3000
40+
develop:
41+
watch:
42+
- action: sync
43+
path: front
44+
target: /code
45+
storybook:
46+
build:
47+
context: front
48+
args:
49+
- NODE_ENV=development
50+
container_name: whombat-storybook
51+
command: ["npm", "run", "storybook"]
52+
ports:
53+
- 6006:6006
54+
develop:
55+
watch:
56+
- action: sync
57+
path: front
58+
target: /code
59+
docs:
60+
build:
61+
context: back
62+
container_name: whombat-docs
63+
ports:
64+
- 8000:8000
65+
command: ["uv", "run", "mkdocs", "serve", "-a", "0.0.0.0:8000"]
66+
develop:
67+
watch:
68+
- action: sync
69+
path: back/docs
70+
target: /code/docs
71+
- action: sync
72+
path: back/mkdocs.yml
73+
target: /code/mkdocs.yml
74+
75+
networks:
76+
public:
77+
volumes:
78+
db-data:

‎front/Dockerfile

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
FROM node:lts
2+
3+
ENV CI=true
4+
ENV PORT=3000
5+
6+
WORKDIR /code
7+
8+
COPY package.json /code/package.json
9+
10+
COPY package-lock.json /code/package-lock.json
11+
12+
RUN npm ci
13+
14+
COPY . /code
15+
16+
CMD [ "npm", "run", "dev" ]

0 commit comments

Comments
 (0)