Code upto v0.2.x

.github/workflows/release-cli.yml

@@ -2,8 +2,8 @@ name: Release Chemotion CLI
 
 on:
   push:
-    branches:
-      - chemotion-cli
+    tags:
+      - "*"
 
 jobs:
   build-release-binary:
@@ -12,28 +12,24 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-go@v3
         with:
-          go-version: "1.18"
+          go-version: "1.19"
           check-latest: true
       - name: Build Go for all OSes
         run: |
           cd  chemotion-cli
           go  mod          verify
-          GOOS=linux   GOARCH=amd64 go  build -o chemotion
-          GOOS=darwin  GOARCH=arm64 go  build -o chemotion.arm.osx
-          GOOS=darwin  GOARCH=amd64 go  build -o chemotion.amd.osx
-          GOOS=windows GOARCH=amd64 go  build -o chemotion.exe
-          mv  chemotion ..
-          mv  chemotion.arm.osx ..
-          mv  chemotion.amd.osx ..
-          mv  chemotion.exe ..
+          GOOS=linux   GOARCH=amd64 go  build -o ../chemotion
+          GOOS=darwin  GOARCH=arm64 go  build -o ../chemotion.arm.osx
+          GOOS=darwin  GOARCH=amd64 go  build -o ../chemotion.amd.osx
+          GOOS=windows GOARCH=amd64 go  build -o ../chemotion.exe
       - name: Release Binaries
         uses: "marvinpinto/action-automatic-releases@latest"
         with:
           repo_token: "${{ secrets.GITHUB_TOKEN }}"
-          automatic_release_tag: "latest"
           prerelease: false
           files: |
             chemotion
             chemotion.arm.osx
             chemotion.amd.osx
             chemotion.exe
+            docker-compose.yml

README.md

@@ -0,0 +1,3 @@
+# Announcement
+
+Please note that the Chemotion CLI tool project has been renamed [ChemCLI and has a new home](https://github.com/Chemotion/ChemCLI). This repository is no longer maintained.

chemotion-cli/CHANGELOG.md

@@ -0,0 +1,87 @@
+# CHANGELOG of Chemotion CLI tool
+
+## Version 0.2.0-alpha
+
+The main changes are as follows:
+
+- `chemotion instance consoles` command that allows you to enter the console of a running instance.
+- `chemotion instance ping` command that checks if the instance is up, running and available at the specified URL.
+- `chemotion advanced update` command that updates the CLI tool itself. The tool now also checks (once a day) if an update to itself is available and displays a reminder if this is the case.
+- `chemotion instance new` now uses the latest availble `docker-compose.yml` file, not a hard-coded one.
+- The tool now copies the entries in the `instances:<instance_name>:environment` section to the `./instances/<instance_folder>/shared/pullin/.env` file whenever an instance is turned on (or restarted). The idea is that a user can edit the `chemotion-cli.yml` file (more) easily.
+- Responsive menus: only actions that make sense are displayed e.g. the main menu shows an `off` option if the selected instance is already running.
+- `Back` option: It is now (mostly) possible to go to the menu above using a `back` option. The tool exits once **a task** is completed -- this is an intended feature.
+- The tool is (milliseconds) slower to start now precisely because i now checks on the status of the instance on launch.
+- Bugfixes
+- _Changes that effect the user's files are as follows.:_
+
+> The first difference is formatting of the `chemotion-cli.yml` file.
+
+- The global keys that handle state of the tool i.e. `selected`, `quiet` and `debug` have now been moved to `cli_state:selected`, `cli_state:quiet` and `cli_state:debug` respectively.
+- The `instances:<instance_name>:address` and `instances:<instance_name>:protocol` keys have been removed. Instead, we have `instances:<instance_name>:accessaddress` which stores the full URL that is used to access the ELN instance.
+- A new key called `instances:<instance_name>:environment` has been introduced. This is now used to create the `shared/pullin/.env` file **everytime** the instance is (re)started. **Please** move all your `key=value` pairs from this `.env` file to the `chemotion-cli.yml` in `key: value` format as sub-keys of the `instances:<instance_name>:environment` key.
+- With these changes, the version of this YAML file has been changed from `"1.0"` to `"1.1"`.
+
+Therefore, if your file looked as follows:
+
+```yaml
+instances:
+  main:
+    address: mynotebook.kit.edu
+    debug: false
+    kind: Production
+    name: main-ee5e5424
+    port: 4000
+    protocol: http
+    quiet: false
+  second:
+    address: localhost
+    debug: false
+    kind: Production
+    name: second-ff6f6535
+    port: 4100
+    protocol: http
+    quiet: false
+selected: main
+version: "1.0"
+```
+
+It should now look as follows:
+
+```yaml
+cli_state:
+  debug: false
+  quiet: false
+  selected: main
+instances:
+  main:
+    accessaddress: http://mynotebook.kit.edu
+    environment:
+      url_host: ifgs6.ifg.kit.edu
+      url_protocol: http
+    kind: Production
+    name: main-ee5e5044
+    port: 4000
+  second:
+    accessaddress: http://localhost:4100
+    environment:
+      url_host: localhost:4100
+      url_protocol: http
+      smtp_port: ...<key-value pairs from /shared/pullin/.env file>...
+    kind: Production
+    name: second-ff6f6535
+    port: 4100
+version: "1.1"
+```
+
+> The second difference is splitting of `docker-compose.yml` file into two files.
+
+So far dockerized installations of Chemotion have relied on `docker-compose.yml` file from [here](https://github.com/ptrxyz/chemotion).
+
+The CLI in version 0.1.x-alpha diverged from this by modifying the file to suit the needs of the CLI by
+
+1. changing the `services:eln:ports` key
+2. including this label on `networks`, `services` and `volumes`: `net.chemotion.cli.project: <instance_name>-<instance_uniqueID>
+3. including names on the `volumes` so that they are named the following: `<instance_name>-<instance_uniqueID>_chemotion_<app|data|db|spectra>`.
+
+Version 0.2.x onwards, we refrain from modifying the `docker-compose.yml` file, making only one change in it (Change 1. is still done.). Changes 2. and 3. are inlcuded in the configuration by adding a new file called `docker-compose.cli.yml` (that we use in addition to the `docker-compose.yml` file). The `docker compose` tool seamlessly merges the two files when reading them.

chemotion-cli/README.md

@@ -1,92 +1,131 @@
 # Chemotion-CLI
 
-##
-
 Chemotion CLI tool is there to help you manage installation(s) of Chemotion on a machine. The goal is to make installation, maintenance and upgradation of Chemotion as easy as possible.
 
-## Installation
+> :information_source: [Link to quick intro video](https://youtu.be/10fk2C6qku0)
+
+## Download
 
-### Download the binary
+### Get the binary
 
-The Chemotion CLI tool is a binary file and needs no installation. The only prerequisite is that you install [Docker Desktop](https://www.docker.com/products/docker-desktop/) (and, on Windows, [WSL](https://docs.microsoft.com/en-us/windows/wsl/install)). Depending on your OS, you can download the lastest release of the CLI from here:
+The Chemotion CLI tool is a binary file and needs no installation. The only prerequisite is that you install [Docker Desktop](https://www.docker.com/products/docker-desktop/) (and, on Windows, [WSL](https://docs.microsoft.com/en-us/windows/wsl/install)). Depending on your OS, you can download the lastest release of the CLI from [here](https://github.com/harivyasi/chemotion/releases/latest). Builds for the following systems are available:
 
-- [Linux, amd64](https://github.com/harivyasi/chemotion/releases/download/latest/chemotion)
-- [Windows, amd64](https://github.com/harivyasi/chemotion/releases/download/latest/chemotion.exe); remember to turn on [Docker integration with WSL](https://docs.docker.com/desktop/windows/wsl/).
-- [macOS, apple-silicon](https://github.com/harivyasi/chemotion/releases/download/latest/chemotion.arm.x)
-- [macOS, amd64](https://github.com/harivyasi/chemotion/releases/download/latest/chemotion.amd.x)
+- Linux, amd64
+- Windows, amd64; remember to turn on [Docker integration with WSL](https://docs.docker.com/desktop/windows/wsl/)
+- macOS, apple-silicon
+- macOS, amd64
+
+Please be sure that you have both, `docker` and `docker compose` commands. This should be the case if you install Docker Desktop following the instructions [here](https://docs.docker.com/desktop/#download-and-install). If you choose to install only Docker Engine, then please make sure that you _also_ have `docker compose` as a command (as opposed to `docker-compose`).
 
 ### Make it an executable
 
 On Linux, make this file executable by doing: `chmod u+x chemotion`.
 
 On Windows, the file should be executable by default, i.e. do nothing.
 
-On macOS, make this file executable by doing: `chmod u+x chemotion.amd.x` or `chmod u+x chemotion.arm.x`. If the there is a security pop-up when running the command, please also `Allow` the executable in `System Preferences > Security & Privacy`.
+On macOS, make this file executable by doing: `chmod u+x chemotion.amd.osx` or `chmod u+x chemotion.arm.osx`. If the there is a security pop-up when running the command, please also `Allow` the executable in `System Preferences > Security & Privacy`.
 
 ### Important Note:
 
-All commands here, and in the documentation, use term `chemotion` to refer to the executable. Depending on your configuration, you may have to use any one of the following:
+All commands here, and all the documentation of the tool, use term `chemotion` to refer to the executable. Depending on your configuration, you may have to use any one of the following:
 
 - `./chemotion`
 - `.\chemotion.exe`
-- `./chemotion.arm.x`
-- `./chemotion.amd.x`
+- `./chemotion.arm.osx`
+- `./chemotion.amd.osx`
 
-### First run
+## First run
 
-#### Make a dedicated folder
+### Make a dedicated folder
 
 Make a folder where you want to store installation(s) of Chemotion. Ideally this folder should be in the largest drive (in terms of free space) of your system. Remember that Chemotion also uses space via Docker (docker containers, volumes etc.) and therefore you need to make sure that your system partition has abundant free space.
 
-#### Install
+### Install
 
 To begin with installation, execute: `chemotion install` and follow the prompt. The first installation can take really long time (15-30 minutes depending on your download and processor speeds).
 
 This will create the first (production-grade) `instance` of Chemotion on your system. Generally, this is suffice if you want to use Chemotion in a single scientific group/lab. By default
 
 - this first instance will be available on port 4000
-- this first instance will be the `chosen` instance (more on this below)
+- this first instance will be the `selected` instance.
+
+> :warning: **chemotion-cli.yml**: Installation also creates a file called `chemotion-cli.yml`. This file is critical as it contains information regarding existing installations. Removing the file will render the CLI clueless about existing installations and it will behave as if Chemotion was never installed. Please do not remove the file. Ideally there should be no need for you to modify it manually.
+
+### The `selected` instance
+
+Once you install multiple instances of Chemotion, the actions of CLI will pertain to only one of them i.e. you will be managing only one of them. This instance is referred to as the `selected` instance and it's name is stored in a local file (`chemotion-cli.yml`). You can do `chemotion instance switch` to switch to another instance.
+
+You can also select an instance _temporarily_ by giving its name to the CLI as a flag when you start it e.g. `chemotion instance status --instance the-other-one`.
 
-#### Start and Stop Chemotion
+### Start and Stop Chemotion
 
-To turn on, or off, the `chosen` instance, issue the commands:
+To turn on, and off, the `chosen` instance, issue the commands:
 
-- `chemotion on`, please wait for a minute before the instance becomes fully active
+- `chemotion on`, and
 - `chemotion off`.
 
-## Uninstallation
+### Upgrading an instance (for versions 1.3 and above)
 
-> Usual warning of "be sure about what you want to do" applies!
+As long as you installed an instance of Chemotion using this tool, the upgrade process is quite straightforward:
 
-You can uninstall everything created by the CLI tool by running: `chemotion advanced uninstall`. Last you can simply delete the downloaded binary itself.
+- First make sure that you have the latest version of this tool. You can check the version of your chemotion binary by doing `chemotion --version`. If necessary, follow the instructions in the [download](#download) section again. Feel free to replace the existing `chemotion` file. DO NOT remove/replace the `chemotion-cli.yml` file.
+- Prepare for update by running `chemotion advanced pull-image`. This will download the latest chemotion image from the internet if not already present on the system. Downloading the image outside of downtime saves you time later on.
+- Schedule a downtime of at least 15 minutes; more if you have a lot of data that needs to backed up. During the downtime, run `chemotion instance backup` to backup your data followed by `chemotion instance upgrade` to update the instance.
 
-# Planned concept for CLI
+### Updating this CLI tool
 
-Following features are planned/thought of:
+Starting from version `0.2.0-alpha`, the tool itself can be updated to the latest version by running `chemotion advanced update`.
 
-- Installation & Deployment: we plan to implement `chemotion instance install` to install a Chemotion instance
-- Upgrade: use `chemotion instance upgrade` to upgrade an existing Chemotion instance
-- Backups: `chemotion snapshot create|restore` to savely store your data somewhere
-- Instance life cycle commands, such as `chemotion instance start|stop|pause|restart|status`
-- Manage Settings: `chemotion settings import|export` to import/export you settings and `chemotion instance configure` to run configuration wizards that help you to create configuration stubs
-- Frequently asked for features for the Chemotion Administrator: `chemotion user show|add|delete|password-reset`, `chemotion system info|rails-shell|shell`
+> :information_source: If you are updating from version `0.1.x-alpha`, please download the version `0.2.x-alpha` and run it in the same place. This will modify the configuration to refect changes described at the bottom of this page.
 
-We plan to follow one of the following layouts, depending on which one proves to be more handy in every day use.
+### Uninstallation
 
-```
-general: cli-executable  <resource>  <command>  <argument>  <flags>
-         └─────┬──────┘  └───┬────┘  └───┬───┘  └───┬────┘  └──┬──┘
-example:    chemotion     instance    restart   MyInstance  --force
-```
+> :warning: be sure about what you want to do!
 
+You can uninstall everything created by the CLI tool by running: `chemotion advanced uninstall`. Last you can simply delete the downloaded binary itself.
+
+## Silent and Debug Use
+
+Almost all features of the CLI can be used in silent mode i.e. without any input from user as long as all required pieces of information have been provided using flags. In silent mode, most of the output from the CLI (but not that of docker) is logged only in the log file, and not put on screen.
+
+To use the CLI in silent mode, add the flag `-q`/`--quiet` to your command. The CLI will then use default values and other flags to try and accomplish the action. Examples:
+
+```bash
+./chemotion install -q --name first-instance --address https://myuni.de:3000
+./chemotion instance switch --name switch-to-this-instance -q
 ```
-general: cli-executable  <command>  <resource>  <argument>  <flags>
-         └─────┬──────┘  └───┬───┘  └───┬────┘  └───┬────┘  └──┬──┘
-example:    chemotion     restart    instance   MyInstance  --force
-```
 
-# Known limitations and bugs
+Similarly, the CLI can be run in Debug mode when you encounter an error. This produces a very detailed log file containing a trace of actions you undertake. Telling us about the error and sending us the log file can help us a lot when it comes to helping you.
+
+## Known limitations and bugs
 
 - The following flags cannot be specified in the configuration (`chemotion-cli.yml`) file:
   - `--config`: because that creates a circular dependency
   - `chemotion off`: does not lead to exit of containers with exit code 0.
+- Everything happens in the folder (and subfolders) where `chemotion` is executed. All files and folders are expected to be there; otherwise failures can happen.
+
+# Planned concept for CLI
+
+The commands have the following general layout:
+
+```
+general: cli-executable  <resource>  <command>  <flags>
+         └─────┬──────┘  └───┬────┘  └───┬───┘  └──┬──┘
+example:    chemotion     instance    restart   --force
+```
+
+Following features are exist:
+
+- ✔ Installation & Deployment: `chemotion install` installs a production instance that is ready to use.
+- ✔ Instance life cycle commands: `chemotion on|off` and `chemotion instance status|stats|list|restart`.
+- ✔ Multiple instances: `chemotion instance add|switch|remove` can be used to manage multiple instances.
+- ✔ Upgrade: use `chemotion instance upgrade` to upgrade an existing Chemotion instance.
+- ✔ Backups: use `chemotion instance backup` to save the data associated with an instance.
+- ✔ Shell access: using `chemotion instance console` to access shell/rails/SQL console of an instance
+
+Following features are planned:
+
+- Restore backup: `chemotion restore`
+- Manage Settings: `chemotion instance settings --import|--export` to import/export settings and to run auto-configuring wizards.
+- Features for the Chemotion Administrator: `chemotion user show|add|delete|password-reset`
+- Command to manage underlying docker installation i.e. free up space and prune network