Capiploy: A Modular Deployment Tool

Capiploy is an interactive CLI tool designed to simplify the deployment process for individual modules and predefined module groups. Built with flexibility in mind, it allows you to create, execute, and manage deployment tasks efficiently.

Features

• Module Deployment: Deploy individual modules with custom logic.
• Group Deployment: Combine and deploy multiple modules in predefined groups.
• Dynamic Module Management: Create new modules and groups on the fly.
• Interactive Menu: Navigate and deploy through a visually rich terminal interface.
• Error Handling: Detailed error messages for failed tasks.
• Logs: Automatically log all deployment activities.

Prerequisites

1. Software Requirements

• Node.js (16+ recommended)
• npm (for dependency management)

2. Permissions

Ensure you have appropriate permissions to execute system-level commands required for deployment.

Project Structure

.
├── deploy.js                 # Main script to run Capiploy
├── package.json              # Project configuration
├── README.md                 # Documentation
└── system
    ├── functions.js          # Core utilities for deployment
    └── templates
        ├── deploy_modules_template.js  # Template for defining modules and groups
        └── module_template.js          # Template for creating new modules

Installation

Global Installation

Install Capiploy globally via npm:

npm install -g capiploy

After global installation, you can run the tool from anywhere using the command:

capi

Configuration

1. Remote Credentials Configuration

Before creating modules or groups, you need to configure your remote credentials. These credentials are stored in the capiploy_data directory located in your home directory.

Configure Remote Credentials:

Run the tool:

capi

Follow the prompts to enter your remote server host, username, and private key path.

Credentials File:

The credentials are saved in capiploy_data/remote_credentials.json.

Ensure your SSH private key is added to the ~/.ssh/authorized_keys file on the remote server.

2. Module Definition

Modules are defined in capiploy_data/deploy_modules.mjs. Add your modules in the MODULES array:

export const MODULES = [
  { name: "backend", path: "capiploy_data/modules/backend.js" },
  { name: "frontend", path: "capiploy_data/modules/frontend.js" },
];

3. Group Definition

Groups are combinations of modules and are defined in the GROUPS array:

export const GROUPS = [
  { name: "Full Deployment", modules: ["capiploy_data/modules/backend.js", "capiploy_data/modules/frontend.js"] },
];

4. Module Template

Create new modules using module_template.js:

import { runTasks } from '../system/functions.js';

export async function deploy() {
  await runTasks('backend', [
    { description: 'Pull latest changes', command: 'git pull origin main' },
    { description: 'Restart server', command: 'systemctl restart backend.service' },
  ]);
}

5. Credentials Configuration

Configure your remote credentials in capiploy_data/remote_credentials.json:

{
  "host": "your_remote_host",
  "username": "your_remote_username",
  "privateKeyPath": "/path/to/your/private/key"
}

Ensure your SSH private key is added to the ~/.ssh/authorized_keys file on the remote server.

Usage

Start Capiploy

Run the tool:

capi

Navigate the Menu

-----------------------------------------
   Capiploy Deployment Tool
-----------------------------------------
1) Configure Remote Credentials
2) Modules Menu
3) Groups Menu
4) Exit
-----------------------------------------
Select an option:

Modules Menu

-----------------------------------------
   Modules Menu
-----------------------------------------
1) Create New Module
2) Return to Main Menu
3) Deploy Backend
4) Deploy Frontend
-----------------------------------------
Select an option:

Groups Menu

-----------------------------------------
   Groups Menu
-----------------------------------------
1) Create New Group
2) Return to Main Menu
3) Deploy Full Deployment
-----------------------------------------
Select an option:

Add New Modules or Groups

Use the built-in options to create new modules or groups dynamically.

Logs

All deployment activities are logged to capiploy_data/logs/deploy.log for audit and troubleshooting purposes.

Example Workflow

1. Configure Remote Credentials

   • Run Capiploy and select "Configure Remote Credentials" from the main menu.
   • Follow the prompts to enter your remote server details.

2. Define a New Module

   • Navigate to the Modules Menu and select "Create New Module".
   • Follow the prompts to create a new module.
   • Add the module to capiploy_data/deploy_modules.mjs.

3. Define a New Group

   • Navigate to the Groups Menu and select "Create New Group".
   • Follow the prompts to create a new group by selecting multiple modules.
   • Add the group to capiploy_data/deploy_modules.mjs.

4. Run Deployment

   • Navigate to the Modules Menu or Groups Menu and select the module or group to deploy.

Manual Configuration and Backup

Opening capiploy_data in a Code Editor

To manually modify module tasks, change credentials, or back up your configuration, open the capiploy_data directory in your preferred code editor.

code ~/capiploy_data

Directory Structure

The capiploy_data directory has the following structure:

capiploy_data/
├── deploy_modules.mjs
├── modules
│   ├── backend.js
│   └── frontend.js
├── package.json
└── remote_credentials.json

• deploy_modules.mjs: Contains the definitions for modules and groups.
• modules/: Directory containing individual module files.
• package.json: Project configuration file.
• remote_credentials.json: Stores remote server credentials.

Editing Modules

To edit the tasks for a specific module, open the corresponding JavaScript file in the modules directory. For example, to edit the backend module:

code ~/capiploy_data/modules/backend.js

Editing Credentials

To manually edit the remote credentials, open the remote_credentials.json file:

code ~/capiploy_data/remote_credentials.json

Backing Up Configuration

To back up your configuration, simply copy the capiploy_data directory to a safe location:

cp -r ~/capiploy_data ~/capiploy_data_backup

Example Module Configuration

Initial Module Template

When you create a new module, it starts with a template like this:

// Replace '<nombre_del_modulo>' with the name of your module
export const tasks = [
  // Define the specific tasks for your module here

  // Example task:
  // {
  //   description: 'Task description',
  //   command: 'command_to_execute',
  // },

  // Add more tasks as needed
];

Configured Module Example

After configuring the module with specific tasks, it might look like this:

const FRONTEND_DIR = '/var/www/html/frontend';
const QUEUE_FRONTEND = 'yourpack_frontend';

export const tasks = [
  {
    description: 'Update code from Git (frontend)',
    command: `git -C ${FRONTEND_DIR} pull origin main`,
  },
  {
    description: 'Restart Frontend Supervisor',
    command: `sudo supervisorctl restart ${QUEUE_FRONTEND}`,
  },
];

Contributing

1. Fork the repository.
2. Create a feature branch:

git checkout -b feature/your-feature

3. Commit your changes:

git commit -m "Add your feature"

4. Push and create a pull request.

License

Capiploy is released under the MIT License. See LICENSE for details.