From 99cd18096bb67c4ee5cc10b9a1cf9fd86ceb067a Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Sun, 7 Sep 2025 08:42:17 -0600 Subject: [PATCH] Add INITIAL_ADMIN_API_KEY documentation - Document environment variable in configuration.md - Add section to API authentication documentation - Include examples in Docker installation guide for both SQLite and MySQL setups - Provide usage instructions for CI/CD and automated deployments --- docs/api/authentication.md | 8 ++++++++ docs/configuration.md | 5 +++++ docs/installation/installation_docker.md | 10 ++++++++++ 3 files changed, 23 insertions(+) diff --git a/docs/api/authentication.md b/docs/api/authentication.md index b386c0cd..f30e4276 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -32,6 +32,14 @@ tokens as you want and also delete them again. When deleting a token, it is immediately invalidated and can not be used anymore, which means that the application can not access the API anymore with this token. +### Initial Admin API Token + +For automated deployments and CI/CD pipelines, Part-DB supports automatically creating an initial admin API token +during database setup. Set the `INITIAL_ADMIN_API_KEY` environment variable to a 64-character random string +(generate with `openssl rand -hex 32`) before running database migrations. Part-DB will create an API token named +"Initial Admin Token" with FULL scope that expires after 1 year. The token can be used immediately with the format +`Bearer tcp_` in the Authorization header. + ### Token permissions and scopes API tokens are ultimately limited by the permissions of the user, which belongs to the token. That means that the token diff --git a/docs/configuration.md b/docs/configuration.md index d4b21781..04653ec3 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -114,6 +114,11 @@ bundled with Part-DB. Set `DATABASE_MYSQL_SSL_VERIFY_CERT` if you want to accept particularly for securing and protecting various aspects of your application. It's a secret key that is used for cryptographic operations and security measures (session management, CSRF protection, etc..). Therefore this value should be handled as confidential data and not shared publicly. +* `INITIAL_ADMIN_API_KEY` (env only): When set to a 64-character random string (generate with `openssl rand -hex 32`), + Part-DB will automatically create an API token named "Initial Admin Token" for the admin user during database + migrations. This token will have FULL scope and expire after 1 year. This is useful for automated deployments, + CI/CD pipelines, and Docker setups where you need immediate API access without manual token creation. The token + can be used with the format `Bearer tcp_` in the Authorization header. * `SHOW_PART_IMAGE_OVERLAY`: Set to 0 to disable the part image overlay, which appears if you hover over an image in the part image gallery diff --git a/docs/installation/installation_docker.md b/docs/installation/installation_docker.md index 232633ab..cf0039f7 100644 --- a/docs/installation/installation_docker.md +++ b/docs/installation/installation_docker.md @@ -75,6 +75,11 @@ services: # Use gravatars for user avatars, when user has no own avatar defined - USE_GRAVATAR=0 + # Automatically create an admin API token during database setup (useful for CI/CD pipelines) + # Generate a 64-character random string with: openssl rand -hex 32 + # The token will be available as: Bearer tcp_ + #- INITIAL_ADMIN_API_KEY=your_64_character_random_string_here + # Override value if you want to show a given text on homepage. # When this is empty the content of config/banner.md is used as banner #- BANNER=This is a test banner
with a line break @@ -146,6 +151,11 @@ services: # However you can add add any other environment configuration you want here # See .env file for all available options or https://docs.part-db.de/configuration.html + # Automatically create an admin API token during database setup (useful for CI/CD pipelines) + # Generate a 64-character random string with: openssl rand -hex 32 + # The token will be available as: Bearer tcp_ + #- INITIAL_ADMIN_API_KEY=your_64_character_random_string_here + # Override value if you want to show to show a given text on homepage. # When this is outcommented the webUI can be used to configure the banner #- BANNER=This is a test banner
with a line break