Merge pull request #55 from Dodelidoo-Labs/develop

v0.12.1

Author: smileBeda

CHANGELOG.md

@@ -4,6 +4,17 @@ 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).
 
+## [0.12.1] - 2026-03-03
+### Added
+- Add a per-user auto-approve toggle so selected non-admin users can add artists directly without manual approval
+- Granular "developer" documentation in /doc folder (living documentation)
+
+### Fixed
+- Fix super-admin bootstrap credential fallback by defaulting blank passwords to `change-me` for consistent reset behavior
+
+### Changed
+- README.md documentation
+
 ## [0.11.0] - 2026-01-21
 ### Added
 - Add OIDC SSO integration with login flow by @tinkermesomething

CONTRIBUTING.md

@@ -1,8 +1,23 @@
-# Contributing
+# Contributing to Sonobarr
 
-1. Clone the repository.
-2. Checkout the `develop` branch: `git checkout develop`.
-3. **Create** a `docker-compose.override.yml` with the following contents:
+Thank you for contributing to Sonobarr. This guide defines the required workflow for local development, testing, and pull requests.
+
+## Branch and Pull Request Policy
+
+- Base all work on the `develop` branch.
+- Open pull requests against `develop`.
+- Keep each pull request focused on one feature or one fix.
+- For substantial non-bugfix work, open an issue first to align on scope.
+
+## Local Development Setup
+
+1. Clone the repository and switch to `develop`:
+   ```bash
+   git clone https://github.com/Dodelidoo-Labs/sonobarr.git
+   cd sonobarr
+   git checkout develop
+   ```
+2. Create `docker-compose.override.yml` with a local source mount and your reverse proxy network:
    ```yaml
    services:
      sonobarr:
@@ -15,27 +30,60 @@
          - ./config:/sonobarr/config
          - /etc/localtime:/etc/localtime:ro
          - ./src:/sonobarr/src
-       #ports:
-       #  - "5000:5000"
+       # ports:
+       #   - "5000:5000"
        networks:
          npm_proxy:
-           ipv4_address: 192.168.97.23 #change as you need
+           ipv4_address: 192.168.97.23 # update for your environment
 
    networks:
      npm_proxy:
        external: true
    ```
-4. Build the image with `sudo docker compose up -d` - later this will re-use the local image.
-5. Make code changes in `src/` or other required files.
-6. Test the changes by restarting the docker image `sudo docker compose down && sudo docker compose up -d` and clearing cache in browser.
-7. Once ready to commit, make sure the build still works as well `sudo docker compose down -v --remove-orphans && sudo docker system prune -a --volumes -f && sudo docker compose up -d`.
-
-### Important
-- We only accept PR's, thus, open a Pull Request on the origin with your code changes against `develop` branch. 
-- A maintainer will always review both code and functionality (User Testing), discuss/approve and finally merge the changes.
-- All changes will be adequately credited in changelog. It is up to you to leave `by xxx` comments in the code. 
-- **Please only commit one feature per PR**.
-- If making substantial changes other than bug fixes please first open a Issue to discuss it.
-
-**Always test your changes with at least two accounts - admin and a common user - in the app, in at least two distinct browser builds (such as safari and chrome, for example).**
-**Remember that if you made changes affecting config (that is, database or configuration) you have to delete the `./config` folder before rebuilding or restarting the app.**
+3. Build and start the local stack:
+   ```bash
+   sudo docker compose up -d
+   ```
+4. Implement your changes in `src/`, `migrations/`, and related project files.
+
+## Validation Requirements
+
+Before opening a pull request, verify the change in a running container:
+
+1. Restart and validate normal startup:
+   ```bash
+   sudo docker compose down && sudo docker compose up -d --build
+   ```
+2. Confirm behavior in the UI and clear browser cache if needed.
+3. Run final clean start validation:
+   ```bash
+   sudo docker compose down -v --remove-orphans
+   sudo docker system prune -a --volumes -f
+   sudo docker compose up -d --build
+   ```
+
+### Manual Test Coverage
+
+- Test as both an admin and a regular user account.
+- Test in at least two different browsers, for example Safari and Chrome.
+- Validate both developer expectations and end-user behavior.
+- Preserve backward compatibility and verify upgrade and downgrade paths for schema changes.
+
+If your change affects configuration or database state, remove `./config` before rebuilding so migrations and initialization paths are tested from a clean state.
+
+## Pull Request Quality Bar
+
+- Include a clear summary of what changed and why.
+- Describe how you tested it, including user roles and browsers used.
+- Note any migration impact, compatibility concerns, or operational risks.
+- Expect maintainer review of both code quality and runtime behavior before merge.
+
+## Attribution and Changelog
+
+Maintainers curate release notes and changelog entries. If you want explicit credit text, include your preferred attribution in the pull request description. Contributors will always be attributed in changelog and release notes.
+
+## AI-Assisted Contributions
+
+AI-assisted contributions are allowed. You are responsible for the submitted code quality and correctness, including security and maintainability.
+
+Low-quality, unreviewed, or non-functional generated code will be rejected. Repeated low-quality submissions after maintainer feedback can result in loss of contribution privileges.

README.md

@@ -157,17 +157,19 @@ All variables can be supplied in lowercase (preferred for `.env`) or uppercase (
 | `similar_artist_batch_size` | `10` | Number of cards sent per batch while streaming results. |
 | `auto_start` | `false` | Automatically start a discovery session on load. |
 | `auto_start_delay` | `60` | Delay (seconds) before auto-start kicks in. |
-| `sonobarr_superadmin_username` | `admin` | Username of the bootstrap admin account. |
-| `sonobarr_superadmin_password` | `change-me` | Password for the bootstrap admin. Set to a secure value before first launch. |
+| `sonobarr_superadmin_username` | `admin` | Username of the bootstrap admin account. If unset or blank, Sonobarr uses `admin`. |
+| `sonobarr_superadmin_password` | `change-me` | Password for the bootstrap admin. If unset or blank, Sonobarr uses `change-me`. |
 | `sonobarr_superadmin_display_name` | `Super Admin` | Friendly display name shown in the UI. |
-| `sonobarr_superadmin_reset` | `false` | Set to `true` **once** to reapply the bootstrap credentials on next start. |
+| `sonobarr_superadmin_reset` | `false` | Set to `true` and restart Sonobarr to reapply bootstrap credentials for the configured username (default `admin`). Set it back to `false` after that restart. |
 | `release_version` | `unknown` | Populated automatically inside the Docker image; shown in the footer. No need to set manually. |
 | `sonobarr_config_dir` | `/sonobarr/config` | Override where Sonobarr writes `app.db`, `settings_config.json`, and migrations. |
 
 > ✅ Docker UID/GID mapping: set `PUID`/`PGID` in `.env`. The entrypoint fixes ownership and then drops privileges to that UID/GID.
 
 > ℹ️ `secret_key` is mandatory. If missing, the app refuses to boot to prevent insecure session cookies. With Docker Compose, make sure the key exists in `.env` and that `.env` is declared via `env_file:` as shown above.
 
+> ℹ️ Super-admin bootstrap applies only to the configured bootstrap username. With `sonobarr_superadmin_reset=true`, Sonobarr updates that user if it exists or creates it if it does not; it does not modify other admin accounts.
+
 ### OIDC SSO Configuration
 
 | Key | Default | Description |

doc/README.md

@@ -0,0 +1,8 @@
+# Technical Documentation
+
+This directory contains developer-facing technical documentation for Sonobarr.
+
+## Index
+
+- [User management and approval flow](./user-management.md)
+- [Super-admin bootstrap behavior](./superadmin-bootstrap.md)

doc/superadmin-bootstrap.md

@@ -0,0 +1,37 @@
+# Super-admin Bootstrap Behavior
+
+## Scope
+
+This document defines the startup bootstrap contract for the super-admin account.
+
+## Environment Variables
+
+Sonobarr reads these variables from environment values:
+
+- `sonobarr_superadmin_username`
+- `sonobarr_superadmin_password`
+- `sonobarr_superadmin_display_name`
+- `sonobarr_superadmin_reset`
+
+If username or password is missing or blank, Sonobarr falls back to:
+
+- Username: `admin`
+- Password: `change-me`
+
+## Startup Behavior
+
+On startup, Sonobarr runs super-admin bootstrap once per process launch:
+
+1. If no admin exists yet, it creates the bootstrap user and sets admin privileges.
+2. If at least one admin exists and `sonobarr_superadmin_reset` is not truthy, bootstrap exits without changes.
+3. If `sonobarr_superadmin_reset` is truthy and the configured bootstrap username already exists, Sonobarr updates its password, display name, and admin flag.
+4. If `sonobarr_superadmin_reset` is truthy and the configured bootstrap username does not exist, Sonobarr creates that user as admin.
+
+Accepted truthy values for `sonobarr_superadmin_reset` are: `1`, `true`, `yes` (case-insensitive).
+
+## Operational Notes
+
+- `sonobarr_superadmin_reset` is evaluated only at startup, so a restart is required.
+- Leave `sonobarr_superadmin_reset=false` during normal operation.
+- For one-time recovery, set `sonobarr_superadmin_reset=true`, restart once, then switch it back to `false`.
+- Reset targets only the configured bootstrap username; other admin users are not rewritten.

doc/user-management.md

@@ -0,0 +1,36 @@
+# User Management And Artist Approval
+
+## Scope
+
+This document describes the user access flags that control account status, administrative privileges, and artist approval behavior.
+
+## User Flags
+
+The `users` table includes these access-control fields:
+
+- `is_active`: Controls whether the user can authenticate.
+- `is_admin`: Grants access to admin routes and direct artist addition.
+- `auto_approve_artist_requests`: Allows non-admin users to add artists directly without waiting for manual admin approval.
+
+## Admin UI Controls
+
+The user management page at `/admin/users` provides toggles for:
+
+- Active account
+- Admin privileges
+- Auto approve artist additions
+
+Admins can set these flags when creating a user and when editing an existing user.
+
+## Artist Addition And Request Flow
+
+Server-side behavior is enforced in `DataHandler`:
+
+- Users with `is_admin = true` or `auto_approve_artist_requests = true` can add artists directly to Lidarr.
+- Users without either flag submit a pending artist request for manual admin approval.
+- Unauthorized direct add attempts are rejected with an "Approval Required" message.
+
+The frontend receives permission metadata from the socket `user_info` payload and renders the action button accordingly:
+
+- Direct-add users see the default add action.
+- Manual-approval users see the request action.

migrations/versions/20260303_01_add_auto_approve_artist_requests_to_users.py

@@ -0,0 +1,44 @@
+"""add auto approve artist requests flag to users
+
+Revision ID: 20260303_01
+Revises: 20251222_01
+Create Date: 2026-03-03 10:00:00.000000
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy import inspect
+
+
+# revision identifiers, used by Alembic.
+revision = "20260303_01"
+down_revision = "20251222_01"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    bind = op.get_bind()
+    inspector = inspect(bind)
+    existing_columns = {column["name"] for column in inspector.get_columns("users")}
+
+    with op.batch_alter_table("users", schema=None) as batch_op:
+        if "auto_approve_artist_requests" not in existing_columns:
+            batch_op.add_column(
+                sa.Column(
+                    "auto_approve_artist_requests",
+                    sa.Boolean(),
+                    nullable=False,
+                    server_default=sa.false(),
+                )
+            )
+
+
+def downgrade():
+    bind = op.get_bind()
+    inspector = inspect(bind)
+    existing_columns = {column["name"] for column in inspector.get_columns("users")}
+
+    with op.batch_alter_table("users", schema=None) as batch_op:
+        if "auto_approve_artist_requests" in existing_columns:
+            batch_op.drop_column("auto_approve_artist_requests")

src/sonobarr_app/bootstrap.py

@@ -1,14 +1,15 @@
 from __future__ import annotations
 
-import secrets
-
 from sqlalchemy.exc import OperationalError, ProgrammingError
 
 from .extensions import db
 from .models import User
 
+DEFAULT_BOOTSTRAP_SUPERADMIN_PASSWORD = "change-me"
+
 
 def bootstrap_super_admin(logger, data_handler) -> None:
+    """Ensure the configured bootstrap super-admin user exists with the expected credentials."""
     try:
         admin_count = User.query.filter_by(is_admin=True).count()
     except (OperationalError, ProgrammingError) as exc:
@@ -22,10 +23,12 @@ def bootstrap_super_admin(logger, data_handler) -> None:
     username = data_handler.superadmin_username
     password = data_handler.superadmin_password
     display_name = data_handler.superadmin_display_name
-    generated_password = False
     if not password:
-        password = secrets.token_urlsafe(16)
-        generated_password = True
+        password = DEFAULT_BOOTSTRAP_SUPERADMIN_PASSWORD
+        logger.warning(
+            "Super-admin password was empty during bootstrap; using fallback default for username %s.",
+            username,
+        )
 
     existing = User.query.filter_by(username=username).first()
     if existing:
@@ -52,11 +55,4 @@ def bootstrap_super_admin(logger, data_handler) -> None:
         db.session.rollback()
         return
 
-    if generated_password:
-        logger.warning(
-            "Generated super-admin credentials. Username: %s Password: %s",
-            username,
-            password,
-        )
-    else:
-        logger.info("Super-admin %s %s.", username, action)
+    logger.info("Super-admin %s %s.", username, action)

src/sonobarr_app/models.py

@@ -9,6 +9,8 @@
 
 
 class User(UserMixin, db.Model):
+    """Application user account with authentication and role flags."""
+
     __tablename__ = "users"
 
     id = db.Column(db.Integer, primary_key=True)
@@ -21,6 +23,7 @@ class User(UserMixin, db.Model):
     listenbrainz_username = db.Column(db.String(120), nullable=True)
     is_admin = db.Column(db.Boolean, default=False, nullable=False)
     is_active = db.Column(db.Boolean, default=True, nullable=False)
+    auto_approve_artist_requests = db.Column(db.Boolean, default=False, nullable=False)
     created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)
     updated_at = db.Column(
         db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False
@@ -39,7 +42,10 @@ def name(self) -> str:
         return self.display_name or self.username
 
     def __repr__(self) -> str:  # pragma: no cover - representation helper
-        return f"<User id={self.id} username={self.username!r} admin={self.is_admin}>"
+        return (
+            f"<User id={self.id} username={self.username!r} "
+            f"admin={self.is_admin} auto_approve={self.auto_approve_artist_requests}>"
+        )
 
 
 class ArtistRequest(db.Model):