@arc-fusion/cli/README.md

CLI for running Arc Fusion on your local machine

# Arc Fusion CLI

This is the CLI tool for running Arc Fusion on your local machine.

## Changelog

You can see the changelog [here](https://redirector.arcpublishing.com/alc/arc-products/pagebuilder/fusion-engine/release-notes/cli-changelog/). You will need to be logged into Okta and have access to Arc Learning Center (ALC).

## Requirements

The following apps/commands are required for the fusion CLI to function properly:

-   [node](https://nodejs.org/en/download/) - This should be the same version of Node your `FUSION_RELEASE` is using (v10 in 2.7.x and earlier, v12 in 2.8.x, and v14 in 3.0+)
-   [npm](https://docs.npmjs.com/getting-started/installing-node) - This should be the default version provided by node (v6 in Node 14 and earlier, v7 in Node 16+)
-   [docker 17.06+](https://docs.docker.com/install/)
-   [docker-compose](https://docs.docker.com/compose/install/#install-compose)

## Installation

### Global install

```sh
npm install -g @arc-fusion/cli
```

will install a command-line script on your system, globally accessible as `fusion`.

### Local install

```sh
npm install --save-dev @arc-fusion/cli
```

will install a command-line script in your repo, locally accessible as `npx fusion` or `npm run fusion`.

## Testing
To test the CLI, you can either use `npm link` in the local folder and `npm link @arc-fusion/cli` in the repo or you can run `npm install --no-save [path to local folder]` in the repo where you want to test it out. Then just run the command you need to test with `npx fusion <command>`.

## Linking

If you are using another npm package and need to test local changes, you will need to use `npm link`. Follow the steps below to understand how to do this.

1. Make sure your node and npm version matches the version used by the `FUSION_RELEASE` image
2. Go to the folder containing your package and npm `npm link`
3. Go to the folder containing your bundle and run `npm link [package name]`
4. If this package is published, make sure it is in the `dependencies` object in your `package.json` file
5. If this package is not published, add it to the `devDependencies` object in your `package.json` file manually (don't use `npm i -D`), and save it
6. Start fusion via `npx fusion start`

## Commands

All commands should be run from within the repository, as `fusion <command>` if installed globally, or `npx fusion <command>` if installed locally.

### daemon [--no-admin]

Run Fusion services in detached mode

### down

Stop and remove containers, networks, images, and volumes

### dump

Export the database into `data/dumps/<timestamp>.tar.gz`

### init

Initialize the directory as a git repo, an npm package, and bootstrap the fusion directory structure

### migrate

Migrate a legacy fusion repository to work with the fusion CLI

### rebuild

Force a webpack rebuild of a running cluster

### start [--no-admin]

Configure a docker-compose cluster to map npm linked modules, then start services.

This is also aliased as `npm start` for convenience.

The start command may also be run with the `--no-admin` flag to run the rendering services without the admin app.

If `FUSION_REPO` is set in the `.env` file of the repo, the local version of fusion will be used for development. This should be the absolute path to the directory the local fusion repo is in.

For themes development, there are a few additional flags you can use:

* `-l` or `--links`: Use the local version of blocks for developement. Can optionally take a comma separated string of blocks to link instead of linking all of them (`-l @org/block1,@org/block2`). This requires that you have `THEMES_BLOCKS_REPO` set in your `.env` file and it should be the absolute path to the directory the local blocks repo is in.
* *New for fusion 2.7.4* When linking an unpublished block, you will need to include `@org/block-name@local` in your blocks.json in addition to using the `-l @org/block-name` flag.
* `-f` or `--rebuild`: Rebuild the webpack image and pull the latest version of the blocks.
* `-p` or `--production`: Force the image to use the published blocks. A developer can use any published tag `canary`, `beta`, `stable`, `hotfix`, or `latest`.

We also allow a few additional environment variables (set in the repo's `.env` file):

* `ENGINE_SDK_REPO`: This is used only for themes development. If set, this will use the local version of the engine sdk for development. This should be the absolute path to the directory the local engine sdk repo is in.
* `CSS_FRAMEWORK_REPO`: This is used only for themes development. If set, this will use the local version of the css framework for development. This should be the absolute path to the directory the local css framework repo is in.
* `THEME_COMPONENTS_REPO`: This is used only for themes development. If set, this will use the local version of the theme components for development. This should be the absolute path to the directory the local theme components repo is in.
* `BLOCK_DIST_TAG`: This is used only for themes development. If set, this will control the version of all installed blocks that don't specify a version. The default is `stable`.
* `ENGINE_HEAP_SIZE`: If set, this changes the amount of memory (in MB) the engine image's node is allowed to use. The default is `2048`.
* `WEBPACK_HEAP_SIZE`: If set, this changes the amount of memory (in MB) the webpack image's node is allowed to use. The default is `4096`.
* `FUSION_RELEASE`: If set, this changes the version of Fusion used for the engine and webpack images. The default is `latest`.
* `PORT`: If set, this changes the port Fusion uses. The default is `80`.
* `DEBUG`: If set, this changes the logs you can see in the terminal. The default is `arc.fusion.render.error` (only log rendering errors). You can set it to `*` to see all logs.

There are a few environment variables you can use for testing/troubleshooting. We don't recommend setting these unless you know what you are doing/were directed to do so by support.

* `ENGINE_SDK_DIST_TAG`: This is used only for engine sdk in themes development. If set, this will control the version of engine sdk dependencies in blocks that don't specify a version.
* `CSS_DIST_TAG`: This is used only for CSS frameworks in themes development. If set, this will control the version of CSS frameworks dependencies in blocks that don't specify a version.
* `THEME_COMPONENTS_DIST_TAG`: This is used only for themes components in themes development. If set, this will control the version of theme components dependencies in blocks that don't specify a version.

### stop

Stop services

### verify

Run webpack on the repo source to ensure it has no compilation errors

### zip

* `-f` or `--force`: Skip verifying the bundle.
* `-n` or `--rename`: Change the generated zip file's name.

Create a zip file that is appropriate for upload into the fusion deployment system