@joshuarileydev/coolify-client

A comprehensive TypeScript client library for interacting with the Coolify API. Coolify is an open-source & self-hostable Heroku / Netlify alternative that allows you to deploy applications, databases, and services with ease.

Features

• 🔥 Full TypeScript support with complete type definitions
• 🛡️ Type-safe API interactions with Zod schema validation
• 🚀 Comprehensive API coverage for all Coolify endpoints
• 📦 Modern ES6+ support with both CommonJS and ESM builds
• 🎯 Simple and intuitive API design
• 📖 Extensive documentation and examples

Installation

npm install @joshuarileydev/coolify-client

Quick Start

import { CoolifyClient } from '@joshuarileydev/coolify-client';

// Initialize the client
const coolify = new CoolifyClient({
  apiUrl: 'https://your-coolify-instance.com',
  apiToken: 'your-api-token',
  teamId: 'your-team-id' // optional
});

// Get Coolify version
const version = await coolify.getVersion();
console.log('Coolify version:', version.data?.version);

// List all applications
const applications = await coolify.listApplications();
console.log('Applications:', applications.data);

// Deploy an application
const deployment = await coolify.deployApplication('app-id', 'v1.0.0');
console.log('Deployment started:', deployment.data?.id);

Configuration

The CoolifyClient accepts a configuration object with the following properties:

| Property | Type | Required | Description | |----------|------|----------|-------------| | apiUrl | string | ✅ | Your Coolify instance URL (e.g., https://coolify.example.com) | | apiToken | string | ✅ | Your Coolify API token | | teamId | string | ❌ | Team ID for team-specific operations |

Getting Your API Token

1. Log into your Coolify instance
2. Go to Settings → API Tokens
3. Create a new API token with the required permissions
4. Copy the token for use in your application

Understanding Coolify Resources and Relationships

Resource Hierarchy

Coolify organizes resources in a hierarchical structure:

Teams
└── Projects
    └── Servers
        └── Applications/Databases/Services

Finding Required IDs and UUIDs

Many API endpoints require specific IDs or UUIDs. Here's how to find them:

1. Project UUID (project_uuid)

// List all projects to find project UUIDs
const projects = await coolify.listProjects();
projects.data.forEach(project => {
  console.log(`Project: ${project.name}, UUID: ${project.id}`);
});

2. Server UUID (server_uuid)

// List all servers to find server UUIDs
const servers = await coolify.listServers();
servers.data.forEach(server => {
  console.log(`Server: ${server.name}, UUID: ${server.id}`);
});

3. GitHub App UUID (github_app_uuid)

To find GitHub App UUIDs:

1. In Coolify UI, go to Settings → GitHub Apps
2. The UUID is shown for each configured GitHub App
3. Or use the API to list GitHub Apps (if endpoint available)

4. Application ID

// List applications to find their IDs
const apps = await coolify.listApplications();
apps.data.forEach(app => {
  console.log(`App: ${app.name}, ID: ${app.id}`);
});

Resource Relationships Example

// Example: Creating a complete application setup

// 1. First, create or identify a project
const project = await coolify.createProject({
  name: 'my-production-project',
  description: 'Production environment'
});
const projectUuid = project.data?.id;

// 2. Create or identify a server
const server = await coolify.createServer({
  name: 'production-server',
  ip: '192.168.1.100',
  user: 'root'
});
const serverUuid = server.data?.id;

// 3. Now you can create an application using these relationships
const app = await coolify.createApplication({
  name: 'my-app',
  project_uuid: projectUuid,
  server_uuid: serverUuid,
  git_repository: 'https://github.com/user/repo',
  git_branch: 'main'
});

API Reference

Applications

// List all applications
const apps = await coolify.listApplications();

// Get a specific application
const app = await coolify.getApplication('app-id');

// Create a new application
const newApp = await coolify.createApplication({
  name: 'my-app',
  git_repository: 'https://github.com/user/repo',
  git_branch: 'main'
});

// Update an application
const updatedApp = await coolify.updateApplication('app-id', {
  description: 'Updated description'
});

// Delete an application
await coolify.deleteApplication('app-id');

// Application lifecycle management
await coolify.startApplication('app-id');
await coolify.stopApplication('app-id');
await coolify.restartApplication('app-id');

// Deploy an application
const deployment = await coolify.deployApplication('app-id', 'v1.0.0');

Create Private GitHub App Application

This endpoint allows you to create an application from a private GitHub repository using a configured GitHub App.

// Create an application from a private GitHub repository
const privateApp = await coolify.createPrivateGithubAppApplication({
  // Required fields
  project_uuid: 'your-project-uuid',      // Get from listProjects()
  server_uuid: 'your-server-uuid',        // Get from listServers()
  github_app_uuid: 'your-github-app-uuid',// From Coolify UI > Settings > GitHub Apps
  git_repository: 'https://github.com/org/private-repo',
  git_branch: 'main',
  name: 'my-private-app',
  
  // Optional fields
  domains: 'app.example.com,www.app.example.com',
  ports_exposes: '3000',
  ports_mappings: '3000:80',
  base_directory: '/app',
  build_pack: 'nixpacks', // or 'dockerfile', 'static', etc.
  install_command: 'npm install',
  build_command: 'npm run build',
  start_command: 'npm start',
  instant_deploy: true,
  
  // Docker-specific options
  dockerfile: './Dockerfile',
  docker_registry_image_name: 'myapp',
  docker_registry_image_tag: 'latest',
  
  // Environment configuration
  environment_name: 'production',
  
  // Advanced options
  custom_labels: 'traefik.enable=true',
  custom_docker_run_options: '--memory=2g',
  custom_nginx_configuration: 'client_max_body_size 100M;',
  watch_paths: './src,./public',
});

console.log('Private app created with UUID:', privateApp.data?.uuid);

Important Notes:

• You must have a GitHub App configured in Coolify before using this endpoint
• The repository must be accessible by the configured GitHub App
• The github_app_uuid can be found in Coolify UI under Settings → GitHub Apps

Databases

// List all databases
const databases = await coolify.listDatabases();

// Get a specific database
const db = await coolify.getDatabase('db-id');

// Create a new database
const newDb = await coolify.createDatabase({
  name: 'my-postgres-db',
  type: 'postgresql'
});

// Delete a database
await coolify.deleteDatabase('db-id');

Servers

// List all servers
const servers = await coolify.listServers();

// Get a specific server
const server = await coolify.getServer('server-id');

// Create a new server
const newServer = await coolify.createServer({
  name: 'production-server',
  ip: '192.168.1.100',
  user: 'root'
});

// Validate server connection
await coolify.validateServer('server-id');

Projects

// List all projects
const projects = await coolify.listProjects();

// Get a specific project
const project = await coolify.getProject('project-id');

// Create a new project
const newProject = await coolify.createProject({
  name: 'my-project',
  description: 'My awesome project'
});

Deployments

// List deployments for an application
const deployments = await coolify.listDeployments('app-id');

// Get a specific deployment
const deployment = await coolify.getDeployment('deployment-id');

// Deploy an application with optional tag
const newDeployment = await coolify.deployApplication('app-id', 'v1.2.0');

Services

// List all services
const services = await coolify.listServices();

// Get a specific service
const service = await coolify.getService('service-id');

// Create a new service
const newService = await coolify.createService({
  name: 'redis-service',
  docker_compose: 'version: "3.8"...'
});

// Service lifecycle management
await coolify.startService('service-id');
await coolify.stopService('service-id');

Teams

// List all teams
const teams = await coolify.listTeams();

// Get a specific team
const team = await coolify.getTeam('team-id');

Error Handling

The client throws errors for failed API requests. You should wrap your calls in try-catch blocks:

try {
  const app = await coolify.getApplication('non-existent-id');
} catch (error) {
  console.error('Failed to get application:', error.message);
}

Response Format

All API responses follow the Coolify API format:

interface CoolifyApiResponse<T> {
  data?: T;
  message?: string;
  success?: boolean;
}

interface ListResponse<T> {
  data: T[];
  links?: {
    first?: string;
    last?: string;
    prev?: string;
    next?: string;
  };
  meta?: {
    current_page: number;
    from?: number;
    last_page: number;
    per_page: number;
    to?: number;
    total: number;
  };
}

TypeScript Support

This library is written in TypeScript and provides comprehensive type definitions for all API endpoints and responses. You'll get full IntelliSense support and compile-time type checking.

import type { 
  Application, 
  Database, 
  Server, 
  CoolifyConfig,
  CreatePrivateGithubAppApplicationRequest,
  CreatePrivateGithubAppApplicationResponse
} from '@joshuarileydev/coolify-client';

const config: CoolifyConfig = {
  apiUrl: 'https://coolify.example.com',
  apiToken: 'your-token'
};

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Support

If you encounter any issues or have questions:

1. Check the Coolify documentation
2. Open an issue on GitHub
3. Join the Coolify Discord community

Changelog

1.1.0

• Added createPrivateGithubAppApplication endpoint for creating applications from private GitHub repositories
• Improved documentation with resource relationship explanations
• Added examples for finding required UUIDs and IDs

1.0.1

• Bug fixes and improvements

1.0.0

• Initial release
• Full TypeScript support
• Complete API coverage for Coolify v4
• Support for applications, databases, servers, projects, deployments, services, and teams

Made with ❤️ for the Coolify community