npm package: @soymaycol/maycontainers
Description: Lightweight containers using proot for Render and serverless environments
Author: SoyMaycol
Latest version: 1.3.6

# MayContainers 🐳

> Enhanced container system for environments like Render, Termux, and serverless platforms  
> **Made with love by SoyMaycol** ❤️

**Created by:** SoyMaycol  
**GitHub:** [@SoySapo6](https://github.com/SoySapo6)

MayContainers provides a comprehensive Docker-like container experience, perfect for environments where Docker is not available like Render.com deployments, Termux, and other restricted platforms.

## 🚀 Features

- **No Docker Required**: Uses proot for containerization
- **Multiple Distros**: Alpine, Debian, Ubuntu, Arch, CentOS, and Fedora
- **Enhanced Configuration**: Ports, volumes, environment variables, and more
- **User Management**: Root and non-root user support
- **Network Configuration**: Port forwarding and DNS configuration
- **Startup Commands**: Automatic command execution on container start
- **Health Checks**: Built-in container health monitoring
- **Process Management**: Advanced process handling and lifecycle management
- **Render Compatible**: Works in serverless and restricted environments
- **Lightweight**: Minimal overhead compared to traditional containers
- **Easy API**: Simple JavaScript interface with extensive options

## 📦 Installation

```bash
npm install @soymaycol/maycontainers
```

The package will automatically try to install proot. If it fails, you can manually install it:

```bash
npx maycontainers install
```

## 🔧 Basic Usage

### JavaScript API

```javascript
const { createContainer, quickRun } = require('maycontainers');

// Create a simple container
const container = createContainer({
  name: 'myapp',
  distro: 'alpine'
});

// Initialize and run commands
await container.init();
await container.run('echo "Hello from container!"');
await container.shell();
```

## 🌟 Advanced Configuration

### Full Configuration Example

```javascript
const container = createContainer({
  name: 'webapp',
  distro: 'alpine',
  version: 'latest',
  
  // Port configuration
  allowedPorts: [3000, '8080:80', { host: 443, container: 443, protocol: 'tcp' }],
  
  // Startup commands
  startupCommands: [
    'apk update',
    'apk add nodejs npm',
    'npm install -g pm2'
  ],
  
  // User management
  enableRoot: false,
  user: 'appuser',
  uid: 1000,
  gid: 1000,
  
  // Environment variables
  environment: {
    NODE_ENV: 'production',
    PORT: '3000',
    DATABASE_URL: 'postgresql://localhost/myapp'
  },
  
  // Volume mounting
  volumes: {
    '/host/app': '/app',
    '/host/data': '/data'
  },
  
  // Network configuration
  hostname: 'myapp-container',
  dnsServers: ['8.8.8.8', '1.1.1.1'],
  networkMode: 'bridge',
  
  // System configuration
  memory: '1024m',
  workingDir: '/app',
  shell: '/bin/bash',
  autostart: true,
  
  // Restart policy
  restartPolicy: 'always', // 'no', 'always', 'on-failure'
  
  // Health check
  healthCheck: {
    cmd: 'curl -f http://localhost:3000/health || exit 1',
    timeout: 30000
  },
  
  // Security options
  capabilities: ['NET_BIND_SERVICE'],
  securityOpt: ['no-new-privileges'],
  
  // Labels for organization
  labels: {
    'app.name': 'webapp',
    'app.version': '1.0.0',
    'environment': 'production'
  }
});
```

### Container Management

```javascript
// Initialize container
await container.init();

// Run commands with options
await container.run('node app.js', {
  cwd: '/app',
  env: { DEBUG: 'true' },
  detached: true,
  timeout: 60000
});

// Execute with custom user
await container.exec('whoami', {
  user: 'root',
  stdio: 'pipe'
});

// Package management
await container.installPackage('curl');
await container.installPackage('nodejs npm');

// Health monitoring
const health = await container.healthCheck();
console.log('Container health:', health.status);

// Container inspection
const info = await container.inspect();
console.log('Container info:', info);

// View logs
const logs = await container.logs({ lines: 50 });
console.log('Container logs:', logs);

// Lifecycle management
await container.stop();
await container.restart();
await container.destroy();
```

## 🐧 Supported Distributions

| Distro | Status | Package Manager | Default Setup |
|--------|--------|----------------|---------------|
| Alpine | ✅ | apk | bash, curl, wget |
| Debian | ✅ | apt | bash, curl, wget |
| Ubuntu | ✅ | apt | bash, curl, wget |
| Arch | ✅ | pacman | bash, curl, wget |
| CentOS | ✅ | yum | bash, curl, wget |
| Fedora | ✅ | dnf | bash, curl, wget |

## 🌐 Perfect for Render.com

```javascript
// Render.com deployment example
const { createContainer } = require('maycontainers');

const container = createContainer({
  name: 'render-app',
  distro: 'alpine',
  allowedPorts: [process.env.PORT || 3000],
  startupCommands: [
    'apk add --no-cache python3 py3-pip',
    'pip3 install -r requirements.txt'
  ],
  environment: {
    PORT: process.env.PORT || '3000',
    NODE_ENV: 'production'
  },
  autostart: true,
  restartPolicy: 'always',
  healthCheck: {
    cmd: `curl -f http://localhost:${process.env.PORT}/health || exit 1`,
    timeout: 30000
  }
});

// Initialize and run
await container.init();
await container.run('python3 app.py');
```

## 📝 API Reference

### MayContainer Class

#### Constructor Options

**Basic Options:**
- `name` (string): Container name
- `distro` (string): Linux distribution
- `version` (string): Distribution version
- `workDir` (string): Host working directory

**Network Options:**
- `allowedPorts` (array): Port configurations
- `hostname` (string): Container hostname
- `dnsServers` (array): DNS server addresses
- `networkMode` (string): Network mode

**User Management:**
- `enableRoot` (boolean): Enable root access
- `user` (string): Default user name
- `uid` (number): User ID
- `gid` (number): Group ID

**System Options:**
- `environment` (object): Environment variables
- `volumes` (object): Volume mappings
- `memory` (string): Memory limit
- `workingDir` (string): Default working directory
- `shell` (string): Default shell
- `autostart` (boolean): Auto-run startup commands

**Advanced Options:**
- `startupCommands` (array): Commands to run on start
- `restartPolicy` (string): Restart behavior
- `healthCheck` (object): Health check configuration
- `capabilities` (array): Container capabilities
- `securityOpt` (array): Security options
- `labels` (object): Container labels

#### Methods

**Core Methods:**
- `init()`: Initialize container and download rootfs
- `run(command, options)`: Run command in container
- `exec(command, options)`: Execute with advanced options
- `shell(options)`: Start interactive shell
- `setup()`: Run distribution setup

**Management Methods:**
- `stop()`: Stop container and processes
- `restart()`: Restart container
- `destroy()`: Remove container completely
- `inspect()`: Get container information
- `getStats()`: Get container statistics

**Utility Methods:**
- `installPackage(packageName)`: Install packages
- `healthCheck()`: Check container health
- `logs(options)`: Get container logs
- `list()`: List all containers

### Quick Functions

```javascript
// Factory function
const container = createContainer(options);

// Quick command execution
await quickRun('node --version', { distro: 'alpine' });

// Container management
const containers = await listContainers(workDir);
await removeContainer('myapp', workDir);
```

## 🔒 Security Features

- Isolated filesystem using proot
- Process isolation and management
- User namespace support
- Configurable capabilities
- Security options support
- No root privileges required on host
- DNS configuration control

## ⚡ Performance

- **Startup**: ~2-5 seconds (vs Docker's 10-30s)
- **Memory**: Minimal overhead with configurable limits
- **Storage**: Efficient rootfs caching
- **CPU**: Native performance (no virtualization)
- **Network**: Optimized port forwarding

## 🛠️ Advanced Examples

### Web Application with Database

```javascript
const webContainer = createContainer({
  name: 'webapp',
  distro: 'alpine',
  allowedPorts: [3000],
  startupCommands: [
    'apk add --no-cache nodejs npm postgresql-client',
    'npm install -g pm2'
  ],
  environment: {
    DATABASE_URL: 'postgresql://user:pass@db:5432/myapp',
    NODE_ENV: 'production'
  },
  volumes: {
    './app': '/app',
    './data': '/data'
  },
  healthCheck: {
    cmd: 'curl -f http://localhost:3000/health',
    timeout: 30000
  },
  restartPolicy: 'always',
  workingDir: '/app'
});

await webContainer.init();
await webContainer.run('npm start');
```

### Multi-Container Setup

```javascript
// Database container
const dbContainer = createContainer({
  name: 'database',
  distro: 'alpine',
  allowedPorts: [5432],
  startupCommands: [
    'apk add --no-cache postgresql postgresql-contrib',
    'mkdir -p /var/lib/postgresql/data',
    'chown postgres:postgres /var/lib/postgresql/data'
  ],
  user: 'postgres',
  volumes: {
    './db-data': '/var/lib/postgresql/data'
  }
});

// Web container
const webContainer = createContainer({
  name: 'webapp',
  distro: 'alpine',
  allowedPorts: [3000],
  startupCommands: [
    'apk add --no-cache nodejs npm',
    'npm install'
  ],
  environment: {
    DATABASE_URL: 'postgresql://postgres@database:5432/myapp'
  },
  volumes: {
    './app': '/app'
  },
  workingDir: '/app'
});

// Initialize both containers
await dbContainer.init();
await webContainer.init();

// Start database first
await dbContainer.run('su -c "initdb -D /var/lib/postgresql/data" postgres');
await dbContainer.run('su -c "pg_ctl -D /var/lib/postgresql/data -l /var/log/postgresql.log start" postgres', { detached: true });

// Start web application
await webContainer.run('npm start');
```

## 🐛 Troubleshooting

### Common Issues

**proot not found:**
```bash
npx maycontainers install
```

**Permission denied:**
```bash
chmod +x node_modules/maycontainers/bin/proot
```

**Port already in use:**
```javascript
// Use different port mapping
allowedPorts: ['3001:3000'] // Host port 3001 -> Container port 3000
```

**Container won't start:**
```javascript
// Check container logs
const logs = await container.logs({ lines: 100 });
console.log(logs);

// Inspect container
const info = await container.inspect();
console.log(info);
```

**Health check failures:**
```javascript
// Check health status
const health = await container.healthCheck();
console.log('Health status:', health);
```

## 🤝 Contributing

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

---

**SoyMaycol**
- GitHub: [@SoySapo6](https://github.com/SoySapo6)
- Created specifically for Render.com deployments and serverless environments

---

## 🙏 Acknowledgments

- Built with love for the developer community
- Special thanks to the proot project
- Designed for modern deployment platforms

---

*Made with ❤️ by SoyMaycol*