portainer-stack-recreate/README.md

A Node.js CLI tool to recreate Portainer Docker stacks with latest images

# Portainer Stack Recreate

A Node.js CLI tool to recreate Portainer Docker stacks with latest images. This tool automates the process of updating and recreating containers in a Portainer stack to ensure they're running the latest images.

## Features

- 🔍 Fetch and identify Portainer stacks
- 📋 Get stack data and configuration files
- 🔄 Update stack configuration
- 📦 Find all containers in a stack
- 🚀 Recreate containers with latest images
- 🎨 Colored console output for better UX
- 🔒 Support for insecure HTTPS connections
- 📝 Comprehensive error handling

## Installation

### Global Installation (Recommended)

```bash
npm install -g portainer-stack-recreate
```

### Local Installation

```bash
npm install portainer-stack-recreate
```

### From Source

```bash
git clone https://github.com/yourusername/portainer-stack-recreate.git
cd portainer-stack-recreate
npm install
npm link
```

## Usage

### Basic Usage

```bash
portainer-stack-recreate \
  --url https://your-portainer-instance.com:9443 \
  --api-key your-portainer-api-key \
  --stack-name your-stack-name
```

### With Insecure HTTPS

If your Portainer instance uses a self-signed certificate:

```bash
portainer-stack-recreate \
  --url https://your-portainer-instance.com:9443 \
  --api-key your-portainer-api-key \
  --stack-name your-stack-name \
  --insecure
```

### Using Short Options

```bash
portainer-stack-recreate \
  -u https://your-portainer-instance.com:9443 \
  -k your-portainer-api-key \
  -s your-stack-name
```

## Options

| Option | Short | Required | Description |
|--------|-------|----------|-------------|
| `--url` | `-u` | Yes | Portainer instance URL (e.g., `https://portainer.example.com:9443`) |
| `--api-key` | `-k` | Yes | Portainer API key |
| `--stack-name` | `-s` | Yes | Name of the stack to update and recreate |
| `--insecure` | | No | Allow insecure HTTPS connections (skip SSL verification) |
| `--version` | `-v` | No | Display version information |
| `--help` | `-h` | No | Display help information |

## Getting Your Portainer API Key

1. Log into your Portainer instance
2. Go to **Account Settings** → **API Keys**
3. Click **Add key**
4. Give it a name and copy the generated key
5. Use this key with the `--api-key` option

## Examples

### Recreate a Production Stack

```bash
portainer-stack-recreate \
  --url https://portainer.production.com:9443 \
  --api-key ptr_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567= \
  --stack-name production-app
```

### Recreate a Development Stack with Self-Signed Certificate

```bash
portainer-stack-recreate \
  --url https://portainer.dev.local:9443 \
  --api-key ptr_dev_key_here \
  --stack-name dev-app \
  --insecure
```

### Using Environment Variables

You can also use environment variables for sensitive data:

```bash
export PORTAINER_URL="https://portainer.example.com:9443"
export PORTAINER_API_KEY="ptr_your_api_key_here"

portainer-stack-recreate \
  --url "$PORTAINER_URL" \
  --api-key "$PORTAINER_API_KEY" \
  --stack-name my-app
```

## What This Tool Does

1. **Fetches Stack List**: Retrieves all stacks from your Portainer instance
2. **Finds Target Stack**: Locates the specified stack by name
3. **Gets Stack Data**: Retrieves the current stack configuration and environment variables
4. **Gets Stack File**: Fetches the stack file (docker-compose.yml) content
5. **Updates Stack**: Updates the stack with current configuration
6. **Finds Containers**: Gets all containers and filters those belonging to the stack
7. **Recreates Containers**: Recreates each container with `PullImage=true` to get latest images

## Output Example

```
🔍 Fetching stack list from https://portainer.example.com:9443 ...
📋 Found stack: my-app (ID: 123, Endpoint: 456)
📋 Getting stack data for my-app (ID: 123)...
📄 Getting stack file for my-app (ID: 123)...
🔄 Updating stack my-app (ID: 123) on endpoint 456...
✅ Stack my-app (ID: 123) updated successfully
🔍 Getting all containers from endpoint 456...
📦 Total containers found: 15
🔍 Filtering containers for stack my-app...
📦 Found 3 containers in stack my-app
🔄 Recreating container /my-app_web_1 (ID: abc123) with PullImage=true...
✅ Container /my-app_web_1 (ID: abc123) recreated successfully
🔄 Recreating container /my-app_db_1 (ID: def456) with PullImage=true...
✅ Container /my-app_db_1 (ID: def456) recreated successfully
🔄 Recreating container /my-app_cache_1 (ID: ghi789) with PullImage=true...
✅ Container /my-app_cache_1 (ID: ghi789) recreated successfully
✅ All containers in stack my-app (ID: 123) recreated successfully with latest images
```

## Error Handling

The tool provides detailed error messages for various scenarios:

- **Missing required options**: Clear indication of what's missing
- **Invalid API key**: Authentication error details
- **Stack not found**: Lists available stacks
- **Network errors**: Connection and timeout information
- **Container recreation failures**: Specific container error details

## Requirements

- Node.js 14.0.0 or higher
- Access to a Portainer instance
- Valid Portainer API key
- Network access to the Portainer API

## Development

### Prerequisites

- Node.js 14.0.0+
- npm

### Setup

```bash
git clone https://github.com/yourusername/portainer-stack-recreate.git
cd portainer-stack-recreate
npm install
```

### Running Locally

```bash
node bin/portainer-stack-recreate.js --help
```

### Publishing to npm

```bash
npm login
npm publish
```

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Support

If you encounter any issues or have questions:

1. Check the [Issues](https://github.com/yourusername/portainer-stack-recreate/issues) page
2. Create a new issue with detailed information
3. Include your Portainer version and Node.js version

## Changelog

### v1.0.1
- Bug fixes and improvements
- Enhanced error handling

### v1.0.0
- Initial release
- Basic stack recreation functionality
- Colored console output
- Command-line argument parsing
- Error handling and validation