francisca Documentation

Francisca is a high-performance, general-purpose indexer written in Rust for systems supporting the Nostr (NIP-35) protocol.

It acts as a bridge between any Nostr relay and media management applications (such as Prowlarr, Jackett, Sonarr, and Radarr).

Key Features

• Nostr Protocol: Direct connection to any Nostr relay using NIP-35.
• Universal Compatibility: Works with Prowlarr, Jackett, and all *arr applications.
• Metadata Enrichment: Automatic integration with TMDB and IMDB.
• Multi-architecture Docker: Supports AMD64, ARM64, and ARMv7.
• Privacy: Optional Tor routing support.

⚠️ Warning: Preview images are for testing only. Do not use them in production.

Key Security Facts

• No Signatures: Unlike release images, preview images are NOT signed with Cosign. This reduces build complexity but means they lack production-grade verification.
• Trust: Do not trust preview images from unknown contributors. Always review the code in the Pull Request before executing the container.
• Secrets: The build process uses DOCKERHUB_USERNAME, DOCKERHUB_TOKEN, and GITHUB_TOKEN internally, but these are not exposed to the image itself.

⚠️ Warning: Preview images should only be used for testing.

Key Security Facts

• No Signing: Unlike release images, preview images are NOT signed with Cosign.
• Production Use: Never use preview images in a production environment.
• Trust: Do not trust preview images from unknown contributors; always review the PR code before running the container.
• Scope: Previews are intended for testing complex features, UI/UX changes, and performance improvements, not for stable deployments.

To get Francisca running in approximately 30 seconds, create a configuration directory and use Docker Compose to pull and start the service. No account or credentials are required for basic operation, as it connects directly to Nostr relays via the NIP-35 protocol.

Steps

1. Create a dedicated configuration directory.
2. Download the official compose.yml.
3. Start the container in detached mode.

# Créer le dossier de configuration
mkdir -p ~/francisca && cd ~/francisca

# Télécharger et démarrer avec Docker Compose
curl -o compose.yml https://raw.githubusercontent.com/UwUDev/francisca/master/docker/compose.yml
docker compose up -d

To develop the Francisca documentation locally, you must have Bun installed. Follow these steps to install dependencies and start the development server.

Note on Internationalization (i18n): In development mode, Docusaurus only loads one locale at a time.

• For French (default): bun start accessible at http://localhost:3000/
• For English: bun start -- --locale en accessible at http://localhost:3001/en/

cd website
bun install
bun start

The primary configuration method is via a config.json file. This file must be placed at the project root for manual installations or mounted as a volume in Docker.

Note: The application will fail to start if no Nostr relays are provided in the relays array.

{
    "relays": ["wss://u2p.anhkagi.net"],
    "bind_ip": "0.0.0.0",
    "bind_port": 8715,
    "log_level": "info",
    "tmdb_token": null,
    "use_tor": false,
    "tor_proxy": "127.0.0.1:9050"
}

The Francisca API is accessible at http://localhost:8715.

Authentication: No authentication is required. The API uses public Nostr relays, so no accounts or credentials are needed to make requests.

To test a specific Pull Request, you must first ensure the PR has been labeled with preview. Once the build is complete (typically 5-10 minutes for updates), you can pull and run the corresponding Docker image. The image tags follow the pattern uwucode/francisca:pr-<PR_NUMBER>.

# 1. Pull the image for PR #456
docker pull uwucode/francisca:pr-456

# 2. Run with a custom configuration volume
docker run -p 8080:8080 \
  -v $(pwd)/test-config:/config \
  uwucode/francisca:pr-456

# 3. Test the endpoint
curl http://localhost:8080/api/endpoint

To enable TMDB and IMDB metadata support in Francisca, you must provide a TMDB API token (specifically a JWT). You can do this by either setting the TMDB_TOKEN environment variable or by adding the key to your config.json file. Note that IMDB support is provided automatically through the TMDB integration when metadata is available.

{
  "TMDB_TOKEN": "YOUR_TMDB_JWT_TOKEN"
}

For PR Authors

To enable a preview for your Pull Request:

1. Open your PR on GitHub.
2. In the right sidebar, click on Labels.
3. Add the preview label.
4. Wait approximately 10-15 minutes for the build to complete.
5. Check the PR comments for the specific docker pull commands provided by the bot.

To update the preview, simply push new commits to your branch. To stop the builds, remove the preview label.

For Reviewers

If you need to test a PR before approving:

1. Request the author to add the preview label, or add it yourself if you have permissions.
2. Wait for the build to finish.
3. Use the Docker commands found in the automated bot comment on the PR.