https://github.com/mrpye/cimpex
Docker image Import Export tool using Rest API Endpoint
https://github.com/mrpye/cimpex
docker-image docker-tar export-docker-images go golang harbor harbor-registry import-docker-image registry rest-api util utilities utility
Last synced: about 1 month ago
JSON representation
Docker image Import Export tool using Rest API Endpoint
- Host: GitHub
- URL: https://github.com/mrpye/cimpex
- Owner: Mrpye
- License: apache-2.0
- Created: 2023-01-26T09:21:47.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-03-28T14:43:22.000Z (about 3 years ago)
- Last Synced: 2025-03-22T07:52:41.166Z (over 1 year ago)
- Topics: docker-image, docker-tar, export-docker-images, go, golang, harbor, harbor-registry, import-docker-image, registry, rest-api, util, utilities, utility
- Language: Go
- Homepage:
- Size: 62.5 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Cimpex - Container Import Export Utility
Export and import docker images from a registry without docker
## Description
The solution enables you to easily export and import Docker containers from a registry without the need to install docker.
It also can be run as a web-server allowing you to perform the Import Export via REST API
## When to use Cimpex
Cimpex can be used when you want to automate the import and export of docker images from a registry if you need to transport images between sites that don't have internet access. Also can be used as part of your CI/CD pipeline.
---
## Requirements
* A Container registry to import or export from.
* you will need to install go 1.8 [https://go.dev/doc/install](https://go.dev/doc/install) to run and install Cimpex
---
## Project folders
Below is a description cimpex project folders and what they contain
| Folder | Description |
|-----------|---|
| charts | Contains the helm chart for cimpex |
| docs | Contains the swagger documents |
| documents | Contains cli and api markdown files |
| modules | Contains cimpex modules and code |
| config | Contains Example payload config files |
| cmd | Contains code for cimpex CLI |
| | |
---
## Installation
```yaml
go install github.com/Mrpye/cimpex
```
## Run as a container
1. Clone the repository
```
git clone https://github.com/Mrpye/cimpex.git
```
2. Build the container as API endpoint
```
sudo docker build . -t cimpex:v1.0.0 -f Dockerfile
```
3. Run the container
```
sudo docker run -d -p 9020:8080 --name=cimpex --restart always -v /host_path/images:/go/bin/images --env=BASE_FOLDER=/go/bin/images --env=WEB_IP=0.0.0.0 --env=WEB_PORT=8080 -t cimpex:1.0.0
```
---
### Environment variables
- BASE_FOLDER (set where the images will be exported)
- WEB_IP (set the listening ip address 0.0.0.0 allow from everywhere)
- WEB_PORT (set the port to listen on)
---
## How to use Cimpex CLI
Check out the CLI documentation [here](./documents/cimpex.md)
---
# Using the API
## Run web server
```bash
cimpex web -f /go/bin/images -p 8080 -i 0.0.0.0
```
---
## Examples
Export image from a registry
Export and image fromm a registry with no authentication
``` bash
curl --location --request POST 'http://localhost:8080/export' \
--header 'Content-Type: application/json' \
--data-raw '{
"target":"cimpex:v1.0.0",
"tar":"cimpex-v1-0-0.tar",
"ignore_ssl":true
}
```
Export from a registry with authentication
```bash
curl --location --request POST 'http://localhost:8080/export' \
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
--header 'Content-Type: application/json' \
--data-raw '{
"target":"127.0.0.1/library/cimpex:v1.0.0",
"tar":"cimpex-v1-0-0.tar",
"ignore_ssl":true
}
```
Export multiple images from a registry
## Export images from a registry
``` bash
curl --location --request POST 'http://localhost:8080/exports' \
--header 'Content-Type: application/json' \
--data-raw '[{
"target":"cimpex:v1.0.0",
"tar":"cimpex-v1-0-0.tar",
"ignore_ssl":true
},
{
"target":"helm-api:v1.0.0",
"tar":"helm-api-v1-0-0.tar",
"ignore_ssl":true
}
]
```
Import image to a registry
Import an image and specify the name at tag to use
```bash
curl --location --request POST 'localhost:8080/import' \
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
--header 'Content-Type: application/json' \
--data-raw '{
"target":"library/bind:test",
"tar":"bind-latest.tar",
"ignore_ssl":true
}'
```
Import an image and use the name at tag from the tar file
```bash
curl --location --request POST 'localhost:8080/import' \
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
--header 'Content-Type: application/json' \
--data-raw '{
"target":"library/",
"tar":"bind-latest.tar",
"ignore_ssl":true
}'
```
## Json Payload
- target (location of the docker image import/export)
- tar (name of the tar file will be saved in the export folder)
- ignore_ssl (Ignore ssl cert)
Import images to a registry from the BASE_FOLDER
folder
Import an images and imports to the target registry
```bash
curl --location 'localhost:8080/imports' \
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
--header 'Content-Type: application/json' \
--data '{
"target":"127.0.0.1/library/",
"ignore_ssl":true
}'
```
## Json Payload
- target (the docker registry)
- ignore_ssl (Ignore ssl cert)
List images in the folder
```bash
curl --location --request POST ''http://localhost:8080/list' \
--header 'Content-Type: application/json'
```
Test is alive
```bash
curl --location --request GET ''http://localhost:8080/'
```
Return OK
---
## cimpex Helm chart
This guide will show you how to build the helm chart package for cimpex, you will need to have helm installed to build the package.
1. Build the helm chart package for cimpex
```bash
# change into the chart directory
cd charts
# Package the cimpex chart
helm package cimpex
```
the helm chart package will be saved under the charts folder cimpex-0.1.0.tgz
---
## Update the swagger document
The code below shows you how to update the swagger API documents.
If you need more helm on using these tools please refer to the links below
- gin-swagge [https://github.com/swaggo/gin-swagger](https://github.com/swaggo/gin-swagger)
- swag [https://github.com/swaggo/swag](https://github.com/swaggo/swag)
1. Install swag
```bash
#Install swag
go install github.com/swaggo/swag/cmd/swag
```
2. Update APi document
```bash
#update the API document
swag init
```
3. Update the api.md
```bash
swagger generate markdown -f .\docs\swagger.json --output .\documents\api.md
```
---
# To Do
- improve validation and error handling
---
# 3rd party Libraries
https://github.com/google/go-containerregistry
---
# license
cimplex is Apache 2.0 licensed.