Development Setup

Profilarr functions as both a synchronization tool for end users and a complete development platform for developers. While most users will simply connect to existing databases to receive updates, Profilarr's development capabilities allow for creating, testing, and contributing custom media configurations back to the community through its Git integration.

Setting Up Your Database Repository

To use Profilarr's development features, you'll need a GitHub repository for your database. You have two options:

Option 1: Fork a PSF Database

1. Go to https://github.com/Dictionarry-Hub/database (or any other Profilarr Standard Format Database)
2. Click the "Fork" button in the top-right corner
3. Follow the prompts to complete the fork process
4. Your forked repository will now be ready to use with Profilarr

Option 2: Create a New Database Repository

1. Click the "+" in the top-right corner and select "New repository"
2. Give your repository a name (like "profilarr-database")
3. Set visibility to public or private as needed (it needs to be public if you intend to share it)
4. Click "Create repository"
5. Clone the repository to your local machine
6. Create three folders: custom_formats, regex_patterns, and profiles
7. Add a .gitkeep file in each folder (this empty file is necessary to ensure Git tracks these folders; otherwise, they won’t be included in the repository, which may cause errors in Profilarr)
8. Commit and push these changes to your repository

Development Configuration

Generate a GitHub Personal Access Token (PAT)

To allow Profilarr to connect and push to your remote database, you'll need to generate a GitHub Personal Access Token (PAT). This token gives Profilarr permission to access and update your GitHub repository.

1. Sign in to your GitHub account
2. Go to Settings > Developer settings > Personal access tokens
3. Click "Generate new token"
4. Choose Fine-grained
5. Give your token a descriptive name (e.g., "Profilarr Development")
6. Apply the following permissions:
   • Repository access: Select your database repository
   • Permissions: Set contents and metadata to Read & Write
7. Click "Generate token"
8. Copy your new token (make sure to save it somewhere safe, as you won’t be able to see it again)

Configure Your User Information

You'll also need to provide a username and email for Git. These will be associated with any commits you make to the database:

• Username: This will appear in commit logs and will be visible to other contributors
• Email: This will be used for Git commits and may be visible in public repositories

Create an Environment File

Create a .env file with the following information. This is required for database contributions:

GIT_USER_NAME=your_username
GIT_USER_EMAIL=your_email
PROFILARR_PAT=your_github_pat

⚠ Security Note: Avoid committing .env files containing secrets to public repositories. If working on a shared system, store credentials in a separate .env.local file or configure them directly in Docker. To ensure these files are ignored by Git, add the following entry to your .gitignore file:

.env
.env.local

Setup

With your credentials configured, you can now deploy Profilarr for development.

Docker Compose (recommended)

services:
  profilarr:
    image: santiagosayshey/profilarr:latest # or :beta for pre-release versions
    container_name: profilarr
    ports:
      - 6868:6868
    volumes:
      - /path/to/your/data:/config
    environment:
      - TZ=UTC # Set your timezone
    env_file:
      - .env # Required for database contributions
    restart: unless-stopped

Docker CLI

docker run -d \
  --name=profilarr \
  -p 6868:6868 \
  -v /path/to/your/data:/config \
  -e TZ=UTC \
  --env-file .env \
  --restart unless-stopped \
  santiagosayshey/profilarr:latest # or :beta for pre-release versions

Unraid

For Unraid users, the Profilarr Community App includes placeholders for required environment variables. To enable development mode, you must replace these placeholders with your actual credentials:

• GIT_USER_NAME
• GIT_USER_EMAIL
• PROFILARR_PAT

Verification

To confirm that everything is set up correctly, check the startup logs for Git user initialization. The logs should include entries similar to the following:

profilarr   | 2025-03-18 20:08:35 - app.init - INFO - Initializing Git user
profilarr   | 2025-03-18 20:08:35 - app.init - INFO - Configuring Git user
profilarr   | 2025-03-18 20:08:35 - app.init - DEBUG - Retrieved Git config: Name - santiagosayshey, Email - user@example.com
profilarr   | 2025-03-18 20:08:35 - app.db.queries.settings - DEBUG - PAT status verified
profilarr   | 2025-03-18 20:08:35 - app.init - INFO - Git user configuration completed
profilarr   | 2025-03-18 20:08:35 - app.init - INFO - Git user initialized successfully

Troubleshooting

If you encounter issues with your development setup:

For additional help or to contribute to Profilarr, join our community on GitHub or Discord.

Contributing to Databases

1. Link Your Fork in Profilarr

   • Open Profilarr and navigate to the database settings.
   • Enter the GitHub repository URL of your forked database.

2. Make Changes in Profilarr

   • Use Profilarr's built-in tools to modify or add database entries.
   • Profilarr will handle formatting and validation automatically.

3. Commit and Push Changes

   • Profilarr provides actions to revert, stage, commit, and push changes.
   • After making changes, stage them using the Stage button.
   • Once staged, commit the changes with a commit message.
   • Finally, use the Push button to send your changes to your GitHub fork.
   • Roll back any unwanted changes using the Revert button.

4. Create a Pull Request (PR)

   • Go to your fork on GitHub and navigate to the "Pull Requests" tab.
   • Click "New pull request" and select your fork and branch.
   • Provide a clear description of the changes and submit the PR.
   • Wait for review and approval before merging.

⚠ Editing Databases Directly

While it's possible to edit database files manually in an IDE or on GitHub, this is not recommended unless you fully understand Profilarr’s formatting and validation rules. Profilarr enforces constraints to ensure data integrity, and bypassing these safeguards can lead to:

• Corrupted or invalid files that Profilarr cannot process correctly.
• Unexpected behavior when syncing with Profilarr.
• Inconsistent formatting, leading to rejected updates.

To make modifications, it's strongly advised to use Profilarr’s built-in editing tools whenever possible. If direct edits are necessary, always validate the changes in a local instance of Profilarr before pushing them to the repository.