You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+50-9Lines changed: 50 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -2,15 +2,31 @@
2
2
3
3
ChemCLI, short for Chemotion CLI, is a tool to help you manage Chemotion ELN on a machine. The goal is to make installation, maintenance and upgradation of (multiple instances of) Chemotion as easy as possible.
4
4
5
+
## Important Announcement
6
+
7
+
Have a bug that looks as follows when trying to update?
8
+
9
+
```sh
10
+
pg_dump: error: connection to server at "db" (172.21.0.2), port 5432 failed: FATAL: database "chemotion" does not exist
11
+
```
12
+
13
+
Then please have a look at the `docker-compose.cli.yml` files in the `instances` folder. The section `services.executor.image` should be changed so that it matches `services.eln.image` in the `docker-compose.yml` file. Otherwise, you will likely bug that looks as follows when trying to upgrade:
14
+
15
+
## Note
16
+
17
+
If you are using ChemCLI versions 0.2.0 to 0.2.3, you will have to run the following command to (force) run the auto-update feature: `./chemCLI advanced update --force`. You can also (always) [download a new executable of ChemCLI](#download) to manually update the tool. (Apologies for the bug!)
18
+
19
+
> Please note that support for version 0.1.x will be completely deprecated on 31.12.2023. The codes that help you migrate from version 0.1 to 0.2 will be removed in releases after 31.12.2023.
20
+
5
21
## Compatibility with Chemotion ELN
6
22
7
23
ChemCLI tool supports the following versions of Chemotion ELN:
8
24
9
-
| ELN Version |`docker-compose.yml` file | Supported by chemCLI version|
> Chemotion ELN version [1.4.x](https://github.com/ComPlat/chemotion_ELN/releases/tag/v1.4.1-3) is **not supported** because it requires [manual changes](https://chemotion.net/docs/eln/install_configure/manual_install#only-when-installing-or-upgrading-to-version-141) to the installation after downloading the [`docker-compose.yml`](https://raw.githubusercontent.com/ptrxyz/chemotion/ba4b4620ab2aaa6be32df78189c29970335b1989/docker-compose.yml) file.
16
32
@@ -59,7 +75,7 @@ These binary builds should not rely on libraries of the underlying operating sys
\*On Windows, it is recommended to use [Powershell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) instead of the one provided natively ([confusingly called Windows Powershell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell)). In any case, it is necessary to have `pwsh`or `powershell`in your `$PATH`.
78
+
\*On Windows, it is recommended to use [Powershell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) instead of the one provided natively ([confusingly called Windows Powershell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell)). In any case, it is necessary to have `pwsh` in your `$PATH`.
63
79
64
80
^On macOS, if the there is a security pop-up when running the command, please also `Allow` the executable in `System Preferences > Security & Privacy`.
65
81
@@ -76,7 +92,7 @@ Make a folder where you want to store installation(s) of Chemotion ELN. Ideally
76
92
77
93
### Install
78
94
79
-
To begin with installation, run the executable (`./chemCLI`) and follow the prompt. The first installation can take really long time (15-30 minutes depending on your download and processor speeds). Please be aware that instance names must be lowercase and cannot container periods (`.`).
95
+
To begin with installation, run the executable (`./chemCLI`) and follow the prompt. The first installation can take really long time (15-30 minutes depending on your download and processor speeds). Please be aware that instance names must be lowercase and cannot contain periods (`.`).
80
96
81
97
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
82
98
@@ -98,12 +114,29 @@ To turn on, and off, the `selected` instance, issue the commands:
98
114
-`./chemCLI on`, and
99
115
-`./chemCLI off`.
100
116
117
+
### Backup an instance
118
+
119
+
:::caution WARNING
120
+
This backup process does not backup data that reside out docker e.g. `services` and `shared` folders. These folder need to be backed up by you separately.
121
+
:::
122
+
123
+
You can backup an instance of the ELN, installed using the CLI, by running the following command:
124
+
`./chemCLI instance backup -i <name_of_instance> -q`. This command must be run individually for every instance of Chemotion ELN that you have. Two new backup files are created _for each execution_ of the command inside the `instances/<name_of_instance-xxxxxxx>/shared/backup` folder. (These two files can be used to restore data into a new instance using the `./chemCLI instance restore` command.)
125
+
126
+
If running this as a [cron](https://en.wikipedia.org/wiki/Cron) job, remember to change into the folder where the ChemCLI executable exists. To do this, include `cd path/to/the/folder` in your job script. Therefore an example crontab file that runs at [03:00 on every day-of-week from Tuesday through Saturday](https://crontab.guru/#0_3_*_*_2-6) would look like as follows:
Please also refer to the notes [here](manual_install#backing-up-and-restoring-your-data) for a better understanding of the backup process.
133
+
101
134
### Upgrading an instance (for ELN versions 1.3 and above)
102
135
103
136
As long as you installed an instance of Chemotion using this tool, the upgrade process is quite straightforward:
104
137
105
138
- First make sure that you have the [latest version of this tool](#updating-the-tool).
106
-
- Prepare for update by running `./chemCLI` > `instance` > `upgrade` > `pull image only`. This will download the latest chemotion image from the internet if not already present on the system. Doing this saves you time later (during scheduled downtime).
139
+
- Prepare for update by running `./chemCLI` > `instance` > `upgrade` > `pull image only`. This will download the latest Chemotion image from the internet if not already present on the system. Doing this saves you time later (during scheduled downtime).
107
140
- 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 `./chemCLI` > `instance` > `all actions` to backup your data followed by an upgrade of the instance.
108
141
109
142
> When upgrading from ELN version 1.3, please create a backup using chemCLI version 0.2.2 or above. This is because the data backup script provided inside the container is broken and this is fixed by chemCLI tool.
@@ -163,5 +196,13 @@ Similarly, the CLI can be run in Debug mode when you encounter an error. This pr
163
196
164
197
## Known limitations and bugs
165
198
166
-
-`./chemCLI off`: does not lead to exit of containers with exit code 0.
167
199
- Everything happens in the folder (and subfolders) where `./chemCLI` is executed. All files and folders are expected to be there; otherwise failures can happen. The user executing ChemCLI is expected to have all file permissions for this folder.
200
+
- Have a bug that looks as follows when trying to update?
201
+
202
+
```sh
203
+
pg_dump: error: connection to server at "db" (172.21.0.2), port 5432 failed: FATAL: database "chemotion" does not exist
204
+
```
205
+
206
+
Then please have a look at the `docker-compose.cli.yml` files in the `instances` folder. The section `services.executor.image` should be changed so that it matches `services.eln.image` in the `docker-compose.yml` file. Otherwise, you will likely bug that looks as follows when trying to upgrade:
207
+
208
+
- If you are using ChemCLI versions 0.2.0 to 0.2.3, you will have to run the following command to (force) run the auto-update feature: `./chemCLI advanced update --force`. You can also (always) [download a new executable of ChemCLI](#download) to manually update the tool.
0 commit comments