LokiCMS Plugin: GitHub Media Storage

Store and serve media files using GitHub as a storage backend for LokiCMS.

Features

• GitHub as Storage: Use any GitHub repository to store media files
• Auto Repository Creation: Automatically creates the storage repository if it doesn't exist
• Date-Based Organization: Files organized by year/month for easy management
• File Type Validation: Whitelist/blacklist file extensions
• Size Limits: Configurable file and repository size limits
• REST API: Full REST API for file operations
• MCP Tools: Model Context Protocol tools for AI integration
• Public URLs: Files served via GitHub's raw content CDN

Installation

From npm

npm install lokicms-plugin-github-media

From local source

Clone this repository into your LokiCMS plugins/ directory:

cd your-lokicms-project/plugins
git clone https://github.com/MauricioPerera/lokicms-plugin-github-media.git github-media

Configuration

1. Create a GitHub Personal Access Token

1. Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Create a new token with these permissions:
   • Contents: Read and Write
   • Metadata: Read
   • Administration: Read and Write (for auto-creating repositories)

2. Add environment variables

Add to your .env file:

GITHUB_MEDIA_TOKEN=github_pat_your_token_here
GITHUB_MEDIA_OWNER=your-github-username
GITHUB_MEDIA_REPO=lokicms-media

3. Configure the plugin

Add to your plugins.json:

{
  "plugins": [
    {
      "name": "github-media",
      "enabled": true,
      "source": "npm",
      "settings": {
        "token": "${GITHUB_MEDIA_TOKEN}",
        "owner": "${GITHUB_MEDIA_OWNER}",
        "repo": "${GITHUB_MEDIA_REPO:lokicms-media}",
        "branch": "main",
        "uploadPath": "uploads",
        "autoCreateRepo": true,
        "repoVisibility": "public",
        "maxFileSize": 26214400,
        "maxRepoSize": 524288000
      }
    }
  ]
}

For local installation, use:

{
  "name": "github-media",
  "enabled": true,
  "source": "local",
  "path": "./plugins/github-media",
  "settings": { ... }
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | token | string | required | GitHub Personal Access Token | | owner | string | required | GitHub username or organization | | repo | string | lokicms-media | Repository name for storage | | branch | string | main | Branch to use | | uploadPath | string | uploads | Base path for uploads | | autoCreateRepo | boolean | true | Auto-create repo if missing | | repoVisibility | string | public | public or private | | maxFileSize | number | 26214400 | Max file size (25 MB) | | warnFileSize | number | 10485760 | Warn if file > 10 MB | | maxRepoSize | number | 524288000 | Max repo size (500 MB) | | allowedExtensions | string[] | [see below] | Allowed file extensions | | blockedExtensions | string[] | [see below] | Blocked file extensions |

Default Allowed Extensions

Images: jpg, jpeg, png, gif, webp, svg, ico, bmp Documents: pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv Audio: mp3, wav, ogg, m4a Video: mp4, webm, mov Fonts: woff, woff2, ttf, otf, eot Other: json, xml, zip

Default Blocked Extensions

Executables: exe, bat, sh, cmd, msi, dll Scripts: php, py, rb, pl Config: htaccess, env, sql

REST API

All endpoints are available at /api/plugins/github-media/

Health Check

GET /api/plugins/github-media/health

Upload File

POST /api/plugins/github-media/upload
Content-Type: multipart/form-data

file: <binary>

Response:

{
  "success": true,
  "file": {
    "name": "image.png",
    "path": "uploads/2025/01/image-abc12345.png",
    "url": "https://raw.githubusercontent.com/owner/repo/main/uploads/2025/01/image-abc12345.png",
    "size": 12345,
    "sha": "abc123..."
  }
}

List Files

GET /api/plugins/github-media/files
GET /api/plugins/github-media/files?path=2025/01

Get File Info

GET /api/plugins/github-media/files/uploads/2025/01/image.png

Delete File

DELETE /api/plugins/github-media/files/uploads/2025/01/image.png

Storage Usage

GET /api/plugins/github-media/usage

Response:

{
  "used": 1234567,
  "usedFormatted": "1.2 MB",
  "limit": 524288000,
  "limitFormatted": "500.0 MB",
  "usagePercent": 0.24,
  "fileCount": 15,
  "visibility": "public"
}

MCP Tools

The plugin registers these MCP tools for AI integration:

| Tool | Description | |------|-------------| | github-media_upload | Upload a file (base64 encoded) | | github-media_list | List all files | | github-media_delete | Delete a file | | github-media_usage | Get storage statistics |

GitHub Limits & Best Practices

Repository Limits

• Max file size: 100 MB (plugin default: 25 MB)
• Recommended max: 1-5 GB per repository
• Warning threshold: 500 MB (configurable)

Rate Limits

• Authenticated requests: 5,000/hour
• Contents API: Additional limits may apply

Best Practices

1. Use for static assets only - Images, documents, fonts
2. Optimize before upload - Compress images, minify files
3. Monitor usage - Check /usage endpoint regularly
4. Use public repos - Better CDN performance
5. Avoid large files - Keep under 10 MB when possible

License

MIT License - see LICENSE file.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Author

LokiCMS Team