pSpitzner · pSpitzner · Jul 6, 2025 · Jun 6, 2025 · Jun 29, 2025 · Jul 4, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,11 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.0] - upcoming
+## [1.0.0] - 25-07-06
 
 This is a breaking change, you will need to update your configs and delete your beets-flask
 database (**not** the beets db!).
 
+This marks a major milestone for beets-flask, as we now pretty happy with the current features
+and the overall architecture.
+
 ### Changed
 
 -   Migrated backend to quart (the async version of flask)
@@ -23,8 +26,11 @@ database (**not** the beets db!).
 -   Terminal now has a bit of scroll-back and history.
 -   Much better test coverage.
 -   Now using [py2ts](https://github.com/semohr/py2ts) to automatically generate frontend (typescript) types from their backend (python) equivalents.
+-   New and improved logo.
+
+## [0.1.1] - 25-06-08
 
-## [0.1.1] - unreleased
+Small version bump with fixes before jumping to 1.0.0.
 
 ### Added
 

diff --git a/README.md b/README.md
@@ -1,11 +1,12 @@
 <!-- start intro -->
 <p align="center">
-    <h1 align="center">Beets Quart</h1>
+    <h1 align="center">Beets-flask</h1>
 </p>
 
 [![version number](https://img.shields.io/github/package-json/v/pspitzner/beets-flask/main?filename=frontend%2Fpackage.json&label=version&color=blue)](https://github.com/pSpitzner/beets-flask/blob/main/CHANGELOG.md)
-[![docker-hub status](https://img.shields.io/github/actions/workflow/status/pSpitzner/beets-flask/docker_hub.yml?label=docker%20build)](https://github.com/pSpitzner/beets-flask/pkgs/container/beets-flask)
+[![Docker Pulls](https://img.shields.io/docker/pulls/pspitzner/beets-flask)](https://hub.docker.com/r/pspitzner/beets-flask/tags)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?label=license)](https://opensource.org/licenses/MIT)
+[![docker-hub build status](https://img.shields.io/github/actions/workflow/status/pSpitzner/beets-flask/docker_hub.yml?label=docker%20build)](https://github.com/pSpitzner/beets-flask/pkgs/container/beets-flask)
 [![Documentation Status](https://readthedocs.org/projects/beets-flask/badge/?version=latest)](https://beets-flask.readthedocs.io/en/latest/?badge=latest)
 
 <p align="center">
@@ -19,16 +20,16 @@
 <!-- start features -->
 
 -   Autogenerate previews before importing
+-   Auto-Import good matches
 -   Import via GUI
--   Web-Terminal
 -   Undo imports
+-   Web-Terminal
 -   Monitor multiple inboxes
 -   Library view and search
 
 <!-- end features -->
 
-https://github.com/user-attachments/assets/dd526b9d-9351-4f7c-9034-1071e4ff66e6
-
+https://github.com/user-attachments/assets/b7c7ae32-36ac-4950-b2ed-186b80d7075b
 
 ## Motivation
 
@@ -38,7 +39,7 @@ Autotagging music with beets is great. Beets identifies metadata correctly _most
 
 However, if you do want a bit more control, things could be more convenient.
 
-This is the main idea with beets-flask: For all folders in your inbox, we generate a preview of what beets _would do_ and show you those previews. Then it's easy to go through them and import the correct ones, while falling back to terminal for those that were not to your liking.
+This is the main idea with beets-flask: For all folders in your inbox, we generate a preview of what beets _would do_ and show you those previews. Then it's easy to go through them and import the correct ones, or pick other candidates for those that were not to your liking.
 
 <!-- end motivation -->
 
@@ -50,8 +51,11 @@ We provide a docker image with the full beeets-flask setup. You can run it with
 
 **Using docker**
 
+<!-- start setup container -->
+
 ```sh
 docker run -d -p 5001:5001 \
+    -e TZ=Europe/Berlin \
     -e USER_ID=1000 \
     -e GROUP_ID=1000 \
     -v /wherever/config/:/config \
@@ -61,6 +65,8 @@ docker run -d -p 5001:5001 \
     pspitzner/beets-flask:stable
 ```
 
+<!-- end setup container -->
+
 **Using docker compose**
 
 ```yaml
@@ -72,6 +78,7 @@ services:
             - "5001:5001"
         environment:
             # 502 is default on macos, 1000 on linux
+            TZ: Europe/Berlin
             USER_ID: 1000
             GROUP_ID: 1000
         volumes:

diff --git a/backend/beets_flask/server/routes/frontend.py b/backend/beets_flask/server/routes/frontend.py
@@ -14,16 +14,19 @@ async def reverse_proxy(path):
     # not include assets
     if (
         not "assets" in path
-        and not "logo.png" in path
+        and not "logo_beets.png" in path
+        and not "logo_flask.png" in path
         and not path.startswith("favicon.ico")
     ):
         path = "index.html"
 
     # Remove everything infront of assets
     if "assets" in path:
         path = path[path.index("assets") :]
-    if "logo.png" in path:
-        path = path[path.index("logo.png") :]
+    if "logo_beets.png" in path:
+        path = path[path.index("logo_beets.png") :]
+    if "logo_flask.png" in path:
+        path = path[path.index("logo_flask.png") :]
 
     r = await send_from_directory(current_app.config["FRONTEND_DIST_DIR"], path)
     return r
diff --git a/demo.mp4 b/demo.mp4
diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml
@@ -5,6 +5,8 @@ services:
         ports:
             - "5001:5001"
         environment:
+            # Change to your timezone
+            TZ: "Europe/Berlin"
             # 502 is default on macos, 1000 on linux
             USER_ID: 1000
             GROUP_ID: 1000

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -1,3 +1,7 @@
 .table-wrapper table {
     width: 100%;
 }
+
+.icon {
+    vertical-align: middle;
+}
diff --git a/docs/_templates/base.html b/docs/_templates/base.html
@@ -0,0 +1,16 @@
+{% extends "furo/base.html" %}
+
+{%- block scripts %}
+
+<script src="https://unpkg.com/lucide@latest"></script>
+<script>
+    lucide.createIcons({
+        attrs: {
+            class: ['icon'],
+
+        },
+        nameAttr: 'data-lucide'
+    });
+</script>
+
+{% endblock %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -77,4 +77,4 @@
 html_css_files = [
     "custom.css",
 ]
-html_logo = "../frontend/public/logo.png"
+html_logo = "../frontend/public/logo_flask.png"
diff --git a/docs/develop/contribution.md b/docs/develop/contribution.md
@@ -6,37 +6,41 @@ We are always happy to see new contributors! If small or large, every contributi
 
 Some technical knowledge for the following tools is required to get started with the project. If you are not familiar with them, please check out the documentation for each tool and make sure you have them installed.
 
-- [Docker](https://docs.docker.com/get-started/)
-- [Docker Compose](https://docs.docker.com/compose/)
-- [Python](https://www.python.org/downloads/) 3.10 or higher
-- [Node.js](https://nodejs.org/en/download/) 18 or higher
-- [git](https://git-scm.com/downloads)
-- [pnpm](https://pnpm.io/installation) (or any other package manager)
+-   [Docker](https://docs.docker.com/get-started/)
+-   [Docker Compose](https://docs.docker.com/compose/)
+-   [Python](https://www.python.org/downloads/) 3.10 or higher
+-   [Node.js](https://nodejs.org/en/download/) 18 or higher
+-   [git](https://git-scm.com/downloads)
+-   [pnpm](https://pnpm.io/installation) (or any other package manager)
 
 ## Setting Up the Development Environment
 
 1. **Clone the repository:**
+
 ```bash
 git clone https://github.com/pSpitzner/beets-flask
 cd beets-flask
 ```
 
 2.1 **Install the dependencies (backend):**
 We recommend using a virtual environment to manage the dependencies.
+
 ```bash
 cd backend
 pip install -e .[dev]
 ```
 
 2.2 **Install the dependencies (frontend):**
-We use (pnpm)[https://pnpm.io/] to manage the frontend dependencies. You may use any other package manager.
+We use [pnpm](https://pnpm.io/) to manage the frontend dependencies. You may use any other package manager. On macOS you might want to run this command inside the container ([see here](resources/macos)).
+
 ```bash
 cd frontend
 pnpm install --frozen-lockfile
 ```
 
 3. **Run the application in dev mode:**
-Check the docker compose file and edit if necessary.
+   Check the docker compose file and edit if necessary.
+
 ```bash
 cd ../
 # We recommend to create a copy of the docker compose file
@@ -46,6 +50,7 @@ docker compose -f ./docker/docker-compose.dev-local.yaml up --build
 ```
 
 ## Install pre-commit hooks
+
 We automatically check for code style and formatting issues using pre-commit hooks. To install the hooks, run the following command (optional):
 
 ```bash
@@ -78,3 +83,48 @@ pnpm check-types
 ## Submitting a Pull Request
 
 Fork the repository and create a new branch for your changes. Feel free to follow [this guide](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) for more information on how to create a pull request. Once you are done we will review your changes as soon as possible. Please be patient, as we are a small team and may not be able to review your changes immediately.
+
+## Example docker compose
+
+```bash
+git clone https://github.com/pSpitzner/beets-flask.git ./beets_flask_dev
+cd ./beets_flask_dev
+mkdir local
+```
+
+Tweak `docker/docker-compose.dev.yaml` to your needs. Important is to live mount your repo folder:
+
+```yaml
+services:
+    beets-flask:
+        container_name: beets-flask
+        hostname: beets-container
+        build:
+            context: ..
+            dockerfile: docker/Dockerfile
+            target: dev
+        image: beets-flask
+        restart: unless-stopped
+        ports:
+            - "5001:5001"
+            - "5173:5173"
+        environment:
+            USER_ID: 1000
+            GROUP_ID: 1000
+            LOG_LEVEL_BEETSFLASK: DEBUG
+            LOG_LEVEL_OTHERS: WARNING
+        volumes:
+            - ../local/music/:/music/
+            - ../local/config/:/config
+            - ../:/repo/
+```
+
+After first launch you will need to install the frontend packages:
+
+```bash
+docker exec -it -u beetle beets-flask-dev bash
+cd /repo/frontend
+pnpm i
+```
+
+Check the viteserver at `localhost:5173`
diff --git a/docs/develop/resources/docker.md b/docs/develop/resources/docker.md
@@ -1,11 +1,10 @@
 # Docker
 
-We use docker for containerization and deployment of our application. You can find the files needed to build the docker images in the `docker` folder.
+We use docker for containerization and deployment of our application. You can find the files needed to build the docker images in the [`docker`](https://github.com/pSpitzner/beets-flask/tree/main/docker) folder.
 
 Redis-Caching seems to be very persistent and we have not figured out how to completely reset it without _rebuilding_ the container.
 Thus, currently, after code changes that run inside a redis worker `docker-compose up --build` is needed even when live-mounting the repo.
 
-
 ## Entrypoints
 
-We use different entrypoints for the different environments. You can find all scripts in the `docker/entrypoints` folder.
+We use different entrypoints for the different environments. You can find all scripts in the [`docker/entrypoints`](https://github.com/pSpitzner/beets-flask/tree/main/docker/entrypoints) folder.
diff --git a/docs/develop/resources/index.md b/docs/develop/resources/index.md
@@ -2,7 +2,6 @@
 
 This document is meant as a primer for developers who want to get started with our codebase. Once you feel comfortable with the code, you may want to check out our [contribution guide](../contribution.md).
 
-
 ```{admonition} Note
 Feel free to open an issue or a pull request if you have any suggestions or questions.
 ```
@@ -12,6 +11,5 @@ docker.md
 documentation.md
 frontend.md
 backend.md
+macos.md
 ```
-
-
diff --git a/docs/develop/resources/macos.md b/docs/develop/resources/macos.md
@@ -0,0 +1,15 @@
+# macOS
+
+Developing on a macOS host might have some quirks.
+
+-   Quart-reloading works by monitoring for file changes, which might be broken depending on docker-desktops volume-mount driver.
+-   pnpm packages need to be installed from within the container. Installing them natively on the host-side might get you versions that dont work in the container. `docker exec -it -u beetle beets-flask-dev bash`
+-   but pytest, ruff and mypy should works directly on the host :)
+
+## iTerm tmux
+
+You can use iTerm's tmux support to natively connect to the session that we have running in the beets container. Simply create a new iterm profile with the following start command:
+
+```
+ssh -t  your_server "/usr/bin/docker exec -it -u beetle beets-flask /usr/bin/tmux -CC new -A -s beets-socket-term"
+```