FAIR Beacon Repo

The FAIR Beacon plugin transforms your site into a FAIR Repository, allowing you to serve packages directly from your own infrastructure into the FAIR system.

[!NOTE]
This plugin has recently been renamed FAIR Beacon, instead of "Mini FAIR". That's why issues might still reference it as such.

Design Goals

FAIR Beacon is designed to allow plugin and theme vendors to host their own FAIR repository easily, integrating with tools they’re already using. FAIR Beacon is built for small scale hosting for a few packages, not for general use as a mass-hosting repository.

We aim to make it possible for everyone to run FAIR Beacon, with a focus on ease of use and integration with existing tooling.

Requirements

• PHP 8.3 or higher
• WordPress 6.4 or higher
• Persistent Object Cache
• Composer for dependency management
• Git Updater plugin (for integration)

  Local Installation & Development Setup

  1. Clone the Repository

  git clone https://github.com/fairpm/fair-beacon.git
  cd fair-beacon

  2. Install Dependencies

  Install PHP dependencies using Composer:

  composer install

  This will install the required packages:

• yocto/yoclib-multibase - For multibase encoding
• simplito/elliptic-php - For elliptic curve cryptography
• spomky-labs/cbor-php - For CBOR data format handling

  3. WordPress Setup

  Option A: Local WordPress Installation

1. Set up a local WordPress environment using your preferred method:
   • Local by Flywheel
   • XAMPP
   • MAMP
   • Docker
2. Copy the FAIR Beacon plugin to your WordPress plugins directory:

   cp -r /path/to/fair-beacon /path/to/wordpress/wp-content/plugins/fair-beacon

3. Activate the plugin through the WordPress admin interface or via WP-CLI:

   wp plugin activate fair-beacon

   Option B: Using WP-CLI for Development

   If you have WP-CLI installed, you can quickly set up a development environment:

   # Create a new WordPress installation
   wp core download
   wp config create --dbname=fair_beacon_dev --dbuser=root --dbpass=password
   wp core install --url=http://localhost --title=“FAIR Beacon Dev” --admin_user=admin --admin_password=password --admin_email=admin@example.com
   # Create a symlink to the plugin
   ln -s /path/to/fair-beacon wp-content/plugins/fair-beacon
   # Activate the plugin
   wp plugin activate fair-beacon

   4. Install Git Updater

   FAIR Beacon requires Git Updater for package management:

   # Download and install Git Updater
   wp plugin install https://github.com/afragen/git-updater/archive/refs/heads/master.zip --activate

   5. Development Environment Configuration

   Enable WordPress Debug Mode

   Add these lines to your wp-config.php file for development:

   define(‘WP_DEBUG’, true);
   define(‘WP_DEBUG_LOG’, true);
   define(‘WP_DEBUG_DISPLAY’, false);
   define(‘SCRIPT_DEBUG’, true);

   Enable WP-CLI Commands

   FAIR Beacon includes WP-CLI commands for PLC management. Ensure WP-CLI is installed and available in your development environment.

   6. Verify Installation

4. Check that the plugin is active:

   wp plugin list

5. Verify the REST API endpoint is working:

   curl http://your-site.local/wp-json/fair-beacon/v1/packages

6. Access the FAIR Beacon admin page at: http://your-site.local/wp-admin/admin.php?page=fair-beacon

   Development Workflow

   Project Structure

   fair-beacon/
   ├── plugin.php              # Main plugin file
   ├── composer.json           # PHP dependencies
   ├── inc/                    # Core functionality
   │   ├── namespace.php       # Main bootstrap
   │   ├── admin/              # Admin interface
   │   ├── api/                # REST API endpoints
   │   ├── git-updater/        # Git Updater integration
   │   ├── keys/               # Cryptographic key management
   │   └── plc/                # PLC (Public Ledger of Credentials) functionality
   └── vendor/                 # Composer dependencies

   Key Components

• PLC Integration: Handles Decentralized Identifiers (DIDs) for packages
• Git Updater Provider: Integrates with Git Updater for package management
• REST API: Provides endpoints for package metadata (/wp-json/fair-beacon/v1/packages/{did})
• Admin Interface: WordPress dashboard integration for managing DIDs and packages

  Making Changes

1. PHP Code: Edit files in the inc/ directory
2. Dependencies: Update composer.json and run composer install
3. Testing: Use WP-CLI commands for testing PLC functionality:

   wp plc --help

   Debugging

• Check WordPress debug logs in wp-content/debug.log
• Use error_log() for debugging output
• Monitor the REST API responses for package metadata

  Using FAIR Beacon

  Installation for End Users

  FAIR Beacon currently supports integration with Git Updater, with planned support for other tools such as EDD coming soon. To use FAIR Beacon, install the latest version of plugin as well as a supported tool - that is, Git Updater.

  Creating a DID for your package

  Once you’ve got FAIR Beacon installed, you’ll need to create a DID for your package if you don’t already have one. Head to the FAIR Beacon page in your WordPress dashboard, and click “Create New PLC DID…” This will begin the process of creating a new PLC DID for your package - a globally-unique ID identifying your package, which you can take with you even if you change repositories in the future. It will also create two cryptographic keys: a “rotation” key, used to manage the DID’s details, as well as a “verification key”, which is used to sign releases. These keys will be stored in your WordPress database - don’t lose them, as you can’t recover your DID if you lose your rotation key! Once your DID has been created, it’ll be published in the global PLC Directory if you want to double check it. You can also sync changes to the directory via the Dashboard if your site’s URL changes, or (coming soon!) to rotate your keys.

  Distributing your package with your DID

  To start distributing your package, you’ll need to add your DID to your plugin or theme. For plugins, add a Plugin ID: header to your plugin’s PHP file:

  
  <?php
  /**

• Plugin Name: My Example Plugin
• Plugin ID: did:plc:abcd1234dcba
• ...

  For themes, add a `Theme ID:` header to your theme’s `style.css` file:
  ```css
  /*
  Theme Name: My Example Theme
  Theme ID: did:plc:abcd1234dcba
  Theme URI: Https://...

  Ensure your plugin or theme is set up correctly with Git Updater, and that you’re using the same site as you registered your DID with. Once that’s done, you’re ready to go - your package should integrate automatically with the FAIR system! You can use the FAIR Plugin to install your package directly by ID, and once it’s been installed once, discovery aggregators will start to list it. You can double-check your packages by checking the REST API endpoint at /wp-json/fair-beacon/v1/packages/{did} (replace {did} with your package’s DID).

  Contributing

  We welcome contributions! Please see the TSC repository for contribution guidelines, including the code of conduct.

  Development Setup for Contributors

1. Fork the repository
2. Follow the local installation steps above
3. Create a feature branch: git checkout -b feature/your-feature-name
4. Make your changes and test thoroughly
5. Submit a pull request

   Troubleshooting

   Common Issues

• Composer dependencies not loading: Ensure you’ve run composer install after cloning
• Plugin not appearing: Check that the plugin directory is named correctly and placed in wp-content/plugins/
• REST API errors: Verify WordPress permalinks are enabled and working
• PLC command not found: Ensure WP-CLI is properly installed and the plugin is activated

  Getting Help

• Check the FAIR Protocol documentation
• Review the Git Updater documentation
• Open an issue on this repository for bug reports or feature requests

  License

  Copyright 2025 contributors. Licensed under the GNU General Public License, v2 or later. Contributions are welcomed from all! See the TSC repository for contribution guidelines, including the code of conduct.