Buttler

Table of Contents

• Overview
  • Features
  • Planned features
  • Known bugs
• Requirements
• Installation
• GitHub App Setup
  • Option A: GitHub App Manifest Flow (Recommended)
  • Option B: Manual GitHub App Configuration
  • Installation Scope
• Usage
• Screenshots
• Contributing
• License

Overview

Buttler automates CI/CD workflows using Docker and GitHub webhooks

Features

• Dark Mode (see screenshots)
• Mega.io integration to save database backups (see screenshots)
• Hosting applications from a GitHub repository (see screenshots)
  • must have a Dockerfile in its root directory
  • can be a private repo, but ssh key of the hosting machine must be added to Deploy keys
  • Creates a new build image automatically via GitHub webhooks and deploys it
• Database services (see screenshots)
  • Engines:
    • PostgreSQL
    • MySQL (not implemented yet)
    • MongoDB (not implemented yet)
    • Redis
  • can be linked to other services (see screenshots)
• Services dashboard (see screenshots)
• Edit service page (see screenshots)
  • Manage service ports
  • Manage environment variables
  • Copy-paste env variables easily
• Service details page (see screenshots)
  • Container logs (see screenshots)
  • List of build images (see screenshots)
  • Button fir triggering a manual build for custom services (see screenshots)
  • Button for triggering a manual backup for database services (see screenshots)
• Linking services (see screenshots)
  • Creates private network between service containers
  • Custom service inherits necessary env variables automatically for the database (see screenshots)

Planned features

You can find the planned features here

Known bugs

You can see the known bugs here

Requirements

To use Buttler, you'll need the following dependencies installed in your machine:

• Node.js >= v19
• NPM
• Docker
• SQLite

Installation

Install Buttler globally using npm:

npm i -g @omer-x/buttler

GitHub App Setup

Buttler integrates with GitHub via a GitHub App for secure user authentication, webhook event delivery, and repository management.

You can set up the GitHub App using either the automated Manifest flow or by configuring it manually in your GitHub Developer settings.

Option A: GitHub App Manifest Flow (Recommended)

The recommended setup is the streamlined 1-click manifest flow:

1. Launch Buttler and navigate to the setup wizard at http://localhost:2083/install (or https://<your-host>/install).
2. Follow the prompt to automatically register the GitHub App with pre-configured settings, URLs, and permissions.
3. Complete the app registration on GitHub and install the app to your account or organization.
4. Buttler will automatically receive and store the required credentials (Client ID, Client Secret, etc.).

Option B: Manual GitHub App Configuration

If you prefer to create and configure the GitHub App manually:

1. Go to GitHub Settings > Developer settings > GitHub Apps > New GitHub App (or your organization's settings).
2. Configure the following App settings:
   • GitHub App name: Choose a unique name (e.g., Buttler-<your-name>).
   • Homepage URL: https://<your-host> (e.g., http://localhost:2083).
   • Authorization callback URL: https://<your-host>/auth/github
   • Webhook URL: https://<your-host>/api/webhook (or /webhook)
   • Webhook secret: Enter a secret token (optional in local development, recommended in production).
3. Configure the required Permissions:
   • Repository permissions:
     • Contents: Read-only (to clone code and inspect Dockerfile and repository contents)
     • Metadata: Read-only (mandatory permission to inspect repository metadata)
     • Webhooks: Read and write (to subscribe to and manage repository push/event webhooks)
   • User permissions:
     • User permissions > read:user (to access user profile and email identity for authentication)
4. Generate credentials:
   • Under General, note the Client ID and generate a Client secret.
5. In Buttler:
   • Enter your Client ID and Client Secret on the /install setup page (or in Settings).

Installation Scope

When installing the GitHub App onto your personal account or organization:

• Choose "Only select repositories" rather than "All repositories".
• Selecting only the repositories you intend to deploy with Buttler adheres to the principle of least privilege, ensuring Buttler only accesses authorized codebases.
• You can grant or revoke access to additional repositories at any time from your GitHub App installation settings.

Usage

To launch the application

buttler start

Then open your browser and navigate to:

http://localhost:2083

To terminate the application

buttler stop

To relaunch the application

buttler restart

Screenshots

Dark Mode

Settings

Custom service

Database service

List of services

Edit service page

Service details

Manual Build

List of build images

Manual backup

Container logs

Linking services

Auto env inheritance

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any feature requests or bug fixes.

License

This project is licensed under the MIT License. See the LICENSE file for details.