🧨 [NOTE]
🧨 cm-butterfly is currently under development.
🧨 So, we do not recommend using the current release in production.
🧨 Please note that the functionalities of cm-butterfly are not stable and secure yet.
🧨 If you have any difficulties in using cm-butterfly, please let us know.
🧨 (Open an issue or Join the cloud-barista Slack)
- cm-butterfly
- Overview
- Prerequisition
- How to Run
- 1. Project clone from remote git repository
- 2. Create the api environment file ⭐
- 3. CM-Butterfly needs to run with cloud-migrator subsystems.
- 4. CSP User credential registration ⭐⭐
- 5. Subsystem's api host and endpoint configuration
- 6. Self auth settings (Optional)
- 7. Configure Nginx for Backend API and Access Control
- 8. Explore Awesome cm-butterfly
- User Guides
cm-butterfly is a framework that provides a GUI environment for a multi-cloud migration platform. It provides a GUI that can be used in a user-friendly and consistent manner to migrate infrastructure, applications, and data from on-premise or cloud source environments to the cloud environments.
- Ubuntu 22.04 or later
- Go 1.26.5 (api)
- Node 20 (front — see
front/.nvmrc) - Docker engine 25.0.0
git clone https://github.com/cloud-barista/cm-butterfly.gitor if you need specific version with minimize the size
git clone --depth 1 --branch v0.6.0 https://github.com/cloud-barista/cm-butterfly.gitThe api reads its database connection and file paths from environment variables. api/.env is not tracked by git, so create it from the sample before running anything that loads it (for example api/docker-compose.dev.yaml, which reads it through env_file).
cp api/.env.sample api/.envThe sample ships development defaults, so it runs as-is for local development. Change them for any real use — POSTGRES_PASSWORD in particular. If you run the api through cm-mayfly, the compose file supplies these values and you do not need api/.env.
cm-butterfly requires execution on each server because it uses the open APIs of several subsystems that make up the cloud migrator project.
To execute each subsystem, you can clone it from the repository of each subsystem.
However, we strongly recommend using the cm-mayfly tool to run the entire platform. It is configured to fully utilize all the features of the cloud-migrator.
Follow the guide in the link. You can run the cloud-migrator with a simple terminal command and access the console.
cm-mayfly, which provides execution and check status at the cloud migration platform level.
If you want to check the detailed information about each subsystem, please visit the link below.
This step is very important, so I've marked it with stars.
In cm-butterfly, it is necessary to register user credentials for each CSP. Registered user's CSP credentials are used for tasks such as provisioning virtual machines in CSP's remote environment while executing workflow, performnace test preperation, or for retrieving price or cost information from CSP.
Among the subsystems used by cm-butterfly, CB-TUMBLEBUG provides a user-friendly process for registering and storing multi-cloud information. It is recommended to register user credentials using the credential registration method provided by CB-TUMBLEBUG.
Follow the guide for initializing CB-Tumblebug to configure multi-cloud information.
⭐ cm-butterfly reads the cm-butterfly/api/conf/api.yaml file to configure the host of the subsystem called by cm-butterfly and the API endpoint of each subsystem.
You can call all the APIs configured in api.yaml through the same request format and response format, and you can call them using the operationId, which is a unique value of each API, to call the API.
🧨NOTE🧨
Except when cm-butterfly and all other servers that are linked are developed in your own local environment, you must use the actual IP address or Domain name, not localhost or 127.0.0.1, because they are accessed from the client's web browser.
Modify the value of services.{subsystem-name}.baseurl. The host currently in use by default is set to the service DNS of the Docker container. If changes are necessary (if there is a IP address or domain), you need to change the corresponding value. Requests will be sent to the URL defined in api.yaml.
cb-spider: #service name
version: 0.12.42(latest)
baseurl: http://cb-spider:1024/spider ## change this end with /spider
auth:
type: basic
username: ${SPIDER_USERNAME}
password: ${SPIDER_PASSWORD}
cb-tumblebug:
version: 0.12.30(latest)
baseurl: http://cb-tumblebug:1323/tumblebug ## change this end with /tumblebug
auth:
type: basic
username: ${TB_API_USERNAME}
password: ${TB_API_PASSWORD}
cm-beetle:
version: 0.6.0(latest)
baseurl: http://cm-beetle:8056/beetle ## change this end with /beetle
auth:
type: basic
username: ${BEETLE_API_USERNAME}
password: ${BEETLE_API_PASSWORD}
# others ...A username or password written as ${VAR} is read from the process environment when the server starts.
Under docker compose the values come from the single shared .env, which cm-mayfly passes into this container.
There is no fallback: a variable that resolves to nothing stops the server and names it, rather than quietly sending something else.
version records the tag the operations were generated from, and it is kept in step with the image tag the lineup runs.
By default, cm-butterfly supports one user with migration privileges. (The featrue that add and delete users are not currently provided.)
When the application starts, it reads ./api/conf/authsetting.yaml, creates user.dat in the same conf folder, and then reads the dat file to process user login.
The default user login information is as follows.
- userId:
cmiguser- userPassword:
cmiguserPassword!
Before running cm-butterfly, if you want to change the value for login credentials, you need to update user login information to authsettings.yaml and run it.
sed -i 's/id: cmiguser/id: what-ever-you-want-id/' ./api/conf/authsetting.yaml
sed -i 's/password: cmiguserPassword!/password: what-ever-you-want-password/' ./api/conf/authsetting.yamlThe frontend of cm-butterfly includes a web server, nginx. It uses nginx's reverse proxy to make http calls to the backend API.
If the API server is not running in the same container environment but is running remotely, you can modify the web server configuration in ./front/nginx.conf to specify a reverse proxy for the backend host.
Currently, the container name defined in docker compose is set to DNS using http which is http://cm-butterfly-api:4000.
# other configuration
proxy_pass <Enter-the-backend-host-here>
Here's a simple terminal command for you, just run it from the root of your project.
sed -i 's|proxy_pass http://cm-butterfly-api:4000;|proxy_pass https://whatever.host.you.want.com|' ./front/nginx.conf
In ./front/nginx.conf, there is the commented part.
# if ($http_origin != "http://localhost") {
# return 403;
# }
This commented block is intended to restrict API access to requests comming only from written domain, enhancing security by preventing unauthorized origins.
To enable this functionaliy, simply remove the # symbols.
If you run it through docker compose, you can see the login page by accessing http://localhost/auth/login. The user credentials are registered with the default ID and password, and if you log in, you can use cm-butterfly, which supports cloud migration.
| Guide | Description |
|---|---|
| Quick Start: Running a Migration | Walk through a migration end to end — register the source, build the models, run the workflow |
| Bulk Import of Source Connections | Register many source connections at once from a CSV or Excel file |
| Running Workflow Tasks in Parallel | Place workflow tasks side by side so they run at the same time |
| Reading the Run Status Screen | What the run view shows at each moment — progress, waiting, failures, and running part of it again |
| Editing a Model as JSON | The table and tree views, searching, and reshaping an array with sort and transform |
| Checking That Source Servers Can Be Reached | What each connection message means, and what to check when a server does not answer |
| Finding Your Way with the Migration Guide | Where to start, what comes next, and how the console works that out |
| Checking That the Linked Services Are Answering | The Service Status screen, and the alert that reaches you wherever you are |