npm package: @mimik/edge-ms-packager
Description: Helps building a compatible docker image to be used by mim OE runtime.
Author: mimik technology inc
Latest version: 1.2.0

# edge-ms-packager [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) [![npm version](https://badge.fury.io/js/%40mimik%2Fedge-ms-packager.svg)](https://www.npmjs.com/package/@mimik/edge-ms-packager)

## Overview
A tool for building Docker-compatible images to be used by mimik OE containers. This packager simplifies the process of converting your serverless functions and microservices into properly formatted Docker archives.

[Learn how to use in your own project](https://developer.mimik.com).

## Configuration

### YAML Configuration File

Create a configuration file (typically `default.yml` or `config/default.yml`) with the following structure:

```yaml
package:
  imageName: your-service-name
  imageIndexFilePath: ./path/to/your/built/file.js
  outputFolder: ./output/directory
```

### Configuration Options

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `imageName` | string | ✅ Yes | Base name for the Docker image (will be suffixed with `-v{apiVersion}`) |
| `imageIndexFilePath` | string | ✅ Yes | Path to your built serverless function/microservice entry point |
| `outputFolder` | string | ✅ Yes | Directory where the packaged Docker tar file will be created |
| `apiVersion` | number | ❌ No | API version for the image (defaults to 1) |

## Versioning

The packager automatically extracts the version from your project's `package.json` file. This version is used in the final Docker archive filename to ensure proper versioning and deployment tracking.

**Version Resolution:**
- The tool reads the `version` field from your `package.json`
- Final archive name format: `{imageName}-v{apiVersion}-{packageVersion}.tar`
- Example: If your `package.json` has `"version": "1.2.3"`, the output will be `my-service-v1-1.2.3.tar`

## Usage

1. **Prepare your serverless function**: Ensure your microservice is built and the entry point file exists at the specified path.

2. **Create configuration**: Set up your YAML configuration file with the required parameters.

3. **Run the packager**: Execute the packaging command to convert your serverless microservice into a Docker-compatible tar file.

The tool will:
- Read the version from your `package.json`
- Validate your configuration and files
- Generate Docker image metadata
- Create the necessary layer structure
- Package everything into a versioned tar file
- Clean up temporary files

## Output Files

After successful execution, you'll find:

- **Main Archive**: `{outputFolder}/{imageName}-v{apiVersion}-{packageVersion}.tar`
- **Console Output**: Detailed logging of each step in the packaging process

## Examples

### Basic Configuration

**package.json:**
```json
{
  "name": "my-api-service",
  "version": "1.0.0",
  "main": "dist/index.js"
}
```

**default.yml:**
```yaml
package:
  imageName: my-api-service
  imageIndexFilePath: ./dist/index.js
  outputFolder: ./docker-output
```

**Output:** `./docker-output/my-api-service-v1-1.0.0.tar`

### Advanced Configuration

**package.json:**
```json
{
  "name": "user-management-service",
  "version": "2.1.5",
  "main": "build/server.js"
}
```

**default.yml:**
```yaml
package:
  imageName: user-management-service
  imageIndexFilePath: ./build/server.js
  outputFolder: ./deployment/images
  apiVersion: 2
```

**Output:** `./deployment/images/user-management-service-v2-2.1.5.tar`

### Version Examples

| package.json version | apiVersion | Final filename |
|---------------------|------------|----------------|
| `"1.0.0"` | `1` (default) | `my-service-v1-1.0.0.tar` |
| `"2.1.3"` | `1` (default) | `my-service-v1-2.1.3.tar` |
| `"1.5.2"` | `3` | `my-service-v3-1.5.2.tar` |

## Support
- [mimik Developer Portal](https://developer.mimik.com)

## License
[MIT licensed](./LICENSE).