Download, Installation and Activation#

cunoFS supports the Linux operating system, and can run inside Docker and other virtual environments such as Hyper-V and Virtualbox.

cunoFS offers a “Scripted Installer” which does not require root privileges to install. We also offer distributions that can be installed using popular Linux package managers. All of our releases are available on GitHub.

Downloading and installing#

The Scripted Installer allows you to install cunoFS without root privileges (no sudo).

Note

For full details about user privileges for installation, see the user guide.

Download the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the latest version from your browser, or run the command:
```
wget https://github.com/cunoFS/cunoFS/releases/latest/download/cuno-glibc-installer.run
```
To install only for the current user, run the following terminal command:
```
sh cuno-glibc-installer.run
```
To install system-wide, run:
```
sudo sh cuno-glibc-installer.run
```
The installation will prompt you to read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the installation. To automate this, you can set the environment variable CUNO_INSTALL_ACCEPT_EULA="yes" (this is equivalent to accepting the EULA).
The installation will prompt you to activate cunoFS by starting a trial or entering a license key. Follow the steps interactively, or automate this step by setting the environment variable CUNO_INSTALL_LICENSE to one of trial | none | <your license key> | <full path to your license key file>.
The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

Download the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the latest version of the self-extracting package for Debian from your browser, or run the command:
```
wget https://github.com/cunoFS/cunoFS/releases/latest/download/cuno_amd64_glibc_deb.run
```
Unpack the archive by running:
```
sh cuno_amd64_glibc_deb.run
```
Please follow the interactive steps, read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the extraction. To automate this, you can set the environment variable CUNO_INSTALL_ACCEPT_EULA="yes" (this is equivalent to accepting the EULA).
The archive and its contents will be unpacked into a directory named cuno_1.2.6_amd64_glibc containing the package itself and additional documents:
```
$ ls cuno_1.2.6_amd64_glibc
cuno_1.2.6_amd64.deb
CUNO-Installation-and-User-Guide.pdf
```
Install cunoFS and its dependencies using apt:

Note

Be sure to use a relative path here, ./, to instruct apt not to search its repositories.
```
sudo apt update
sudo apt install ./cuno_1.2.6_amd64_glibc/cuno_1.2.6_amd64_glibc.deb
```
The installation will prompt you to activate cunoFS by starting a trial or entering a license key. Follow the steps interactively, or automate this step by setting the environment variable CUNO_INSTALL_LICENSE to one of trial | none | <your license key> | <full path to your license key file>.
The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

The Scripted Installer allows you to install cunoFS without root privileges (no sudo).

Note

For full details about user privileges for installation, see the user guide.

Download the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the latest version from your browser, or run the command:
```
wget https://github.com/cunoFS/cunoFS/releases/latest/download/cuno-glibc-installer.run
```
To install only for the current user, run the following terminal command:
```
sh cuno-glibc-installer.run
```
To install system-wide, run:
```
sudo sh cuno-glibc-installer.run
```
The installation will prompt you to read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the installation. To automate this, you can set the environment variable CUNO_INSTALL_ACCEPT_EULA="yes" (this is equivalent to accepting the EULA).
The installation will prompt you to activate cunoFS by starting a trial or entering a license key. Follow the steps interactively, or automate this step by setting the environment variable CUNO_INSTALL_LICENSE to one of trial | none | <your license key> | <full path to your license key file>.
The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

Donwload the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the latest version of the self-extracting package for RHEL from your browser, or run the command:
```
wget https://github.com/cunoFS/cunoFS/releases/latest/download/cuno_x86_64_glibc_rpm.run
```
Unpack the archive by running:
```
sh cuno_x86_64_glibc_rpm.run
```
Please follow the interactive steps, read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the extraction. To automate this, you can set the environment variable CUNO_INSTALL_ACCEPT_EULA="yes" (this is equivalent to accepting the EULA).
The archive and its contents will be unpacked into a directory named cuno_1.2.6_x86_64_glibc containing the package itself and additional documents:
```
$ ls cuno_1.2.6_x86_64_glibc
cuno_1.2.6_x84_64_.rpm
CUNO-Installation-and-User-Guide.pdf
```

Install cunoFS and its dependencies using yum:

sudo yum makecache
sudo yum install ./cuno_1.2.6_x86_64_glibc/cuno_1.2.6_x86_64_glibc.rpm

The installation will prompt you to activate cunoFS by starting a trial or entering a license key. Follow the steps interactively, or automate this step by setting the environment variable CUNO_INSTALL_LICENSE to one of trial | none | <your license key> | <full path to your license key file>.
The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

The Scripted Installer allows you to install cunoFS without root privileges (no sudo).

Note

This installation method assumes you have the libgcc package installed (due to a dependency on libgcc_s.so). On Alpine you can do (may require sudo):

apk add libgcc

Note

For full details about user privileges for installation, see the user guide.

Download the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the latest musl version from your browser, or run the command:
```
wget https://github.com/cunoFS/cunoFS/releases/latest/download/cuno-musl-installer.run
```
To install only for the current user, run the following terminal command:
```
sh cuno-musl-installer.run
```
To install system-wide, run:
```
sudo sh cuno-musl-installer.run
```
The installation will prompt you to read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the installation. To automate this, you can set the environment variable CUNO_INSTALL_ACCEPT_EULA="yes" (this is equivalent to accepting the EULA).
The installation will prompt you to activate cunoFS by starting a trial or entering a license key. Follow the steps interactively, or automate this step by setting the environment variable CUNO_INSTALL_LICENSE to one of trial | none | <your license key> | <full path to your license key file>.
The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

Download the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the latest version of the self-extracting package for Alpine from your browser, or run the command:
```
wget https://github.com/cunoFS/cunoFS/releases/latest/download/cuno_x86_64_musl_apk.run
```

Download the public key for package verification cunoFS.rsa.pub:

wget https://github.com/cunoFS/cunoFS/releases/latest/download/cunoFS.rsa.pub

or create a file called cunoFS.rsa.pub with our public key using this “one-liner” (copy the whole thing, paste into your terminal, hit enter/return):

cat >cunoFS.rsa.pub <<EOF
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAl1TDuzTVhYkr8OPFqU4D
r250/ESsKys92maH7NWC6tprLEaGoTUWi/7XMO33dOOnIuHqWctcxvG/V5sQTRem
PmyozszYyAFNziSO8Wrp9kiCQZ72NyN00j3I+zKG3m/tQ6nVbl5JkWniuPhn6rKQ
mHE72e07+aHGk6a8/cTbkvMe9DA61Uhgu3BOj5+S8ksQhc6k4SFTu3XfhOKu+pIR
U0GJ+/ZtjagvDzwX6Ebf6YS+Skn1CCX4FrLC20CdyyIwf1qvKNG141ireaZlIdp8
4GCOG0UkccAMrACNipRXYfE2/Cx6uiwnwCoqa095CPqPvVXWZY++IlFk/8qdsiJj
FotKjfBd3H68UIMpZF+seIkT/NSIHkyViwUiwrfaMTrIfklZwer+dvVgYvN2M/K/
Eq6QSu9ZzefcE605I14rHya6AnqSVyJx4GZ23tz1fT+l1qA7xC/jJ5jZ04Ni7y8Z
CVEgn/9GD7hgZIc72bD4W8438oxhaALjbZadGz7mfmrp9j96w2pJzW59bpiT+f7I
Kgg57/XM1fjrDQ3xopM5PDTHzxPiIpvMGLmPivvr9gt3L3PoHHjWj3veS34OVPot
RnYU4SBGBHVq0sNZPkeaZpb1bpNyF4t7458F/+RWPVF3S+y0we1q0Q5O9yk6LIfp
OOUcK6r8cF6LV+CdCEE9VbkCAwEAAQ==
-----END PUBLIC KEY-----
EOF

Move the rsa public key into the Alpine directory of trusted signatures /etc/apk/keys (may need sudo):
```
mv cunoFS.rsa.pub /etc/apk/keys/
```
Unpack the archive by running:
```
sh cuno_x86_64_musl_apk.run
```
Please follow the interactive steps, read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the extraction. To automate this, you can set the environment variable CUNO_INSTALL_ACCEPT_EULA="yes" (this is equivalent to accepting the EULA).
The archive and its contents will be unpacked into a directory named cuno_1.2.6_x86_64_musl containing the package itself and additional documents:
```
$ ls cuno_1.2.6_x86_64_musl
cuno_1.2.6_x84_64_.apk
CUNO-Installation-and-User-Guide.pdf
```

Install cunoFS and its dependencies using apk (may need sudo):

apk add ./cuno_1.2.6_x86_64_musl/cuno_1.2.6_x86_64_musl.apk

The installation will prompt you to activate cunoFS by starting a trial or entering a license key. Follow the steps interactively, or automate this step by setting the environment variable CUNO_INSTALL_LICENSE to one of trial | none | <your license key> | <full path to your license key file>.
The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

Most Linux distributions use the GNU Project’s C standard library (glibc). This installer/version is compatible with all such Linux distributions.

The Scripted Installer allows you to install cunoFS without root privileges (no sudo).

Note

For full details about user privileges for installation, see the user guide.

Download the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the latest version from your browser, or run the command:
```
wget https://github.com/cunoFS/cunoFS/releases/latest/download/cuno-glibc-installer.run
```
To install only for the current user, run the following terminal command:
```
sh cuno-glibc-installer.run
```
To install system-wide, run:
```
sudo sh cuno-glibc-installer.run
```
The installation will prompt you to read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the installation. To automate this, you can set the environment variable CUNO_INSTALL_ACCEPT_EULA="yes" (this is equivalent to accepting the EULA).
The installation will prompt you to activate cunoFS by starting a trial or entering a license key. Follow the steps interactively, or automate this step by setting the environment variable CUNO_INSTALL_LICENSE to one of trial | none | <your license key> | <full path to your license key file>.
The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

Some Linux distributions use the musl C standard library. This installer/version is compatible with all such Linux distributions. These instructions will assume you are using Alpine or a derivative.

The Scripted Installer allows you to install cunoFS without root privileges (no sudo).

Note

This installation method assumes you have the libgcc package installed (due to a dependency on libgcc_s.so). On Alpine you can do (may require sudo):

apk add libgcc

Note

For full details about user privileges for installation, see the user guide.

Download the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the latest musl version from your browser, or run the command:
```
wget https://github.com/cunoFS/cunoFS/releases/latest/download/cuno-musl-installer.run
```
To install only for the current user, run the following terminal command:
```
sh cuno-musl-installer.run
```
To install system-wide, run:
```
sudo sh cuno-musl-installer.run
```
The installation will prompt you to read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the installation. To automate this, you can set the environment variable CUNO_INSTALL_ACCEPT_EULA="yes" (this is equivalent to accepting the EULA).
The installation will prompt you to activate cunoFS by starting a trial or entering a license key. Follow the steps interactively, or automate this step by setting the environment variable CUNO_INSTALL_LICENSE to one of trial | none | <your license key> | <full path to your license key file>.
The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

A fully native Mac client is coming soon!

You can currently install cunoFS on your Mac directly, or inside a container. Installing cunoFS on your Mac directly will allow you to use cuno-mac, our handy tool for launching Linux containers that automatically have your local installation of cunoFS available inside them.

Note

For those on Apple Silicon (ARM) Macs, macOS 13.0 Ventura or later is required.

All Mac users require a virtualisation/containerisation software to be installed and set up.
We fully support usage of Docker and Rancher Desktop. Docker is assumed in these guides.

Some settings should be changed to use cunoFS:
We recommend changing the file sharing implementation to VirtioFS:

Open Docker Desktop’s Settings panel

Open the General section.

For the setting Choose file sharing implementation for your containers select VirtioFS.

Use the Apply & Restart button to save the change.
We recommend using the Apple Virtualization Framework (VZ), and the VirtioFS file sharing implementation:

Open Rancher Desktop’s Preferences panel.

Open the Virtual Machine section.

Open the Emulation tab, and set Virtual Machine Type to VZ.

Open Volumes tab, and set the Mount Type to virtiofs.

Use the Apply button to save the changes.

In order to use the cuno-mac utility with Rancher, the “dockerd” (moby) container engine must be used:

Open Rancher Desktop’s Preferences panel.

Open the Container Engine section.

In the General tab, set the Container Engine to dockerd (moby).

Use the Apply button to save the change.
You may also use OrbStack for Mac and find it to be faster, but cuno-mac native support is not available in this case.

Unfortunately, colima is not currently supported.
We assume usage of Docker in these guides, but any of following containerisation technologies is supported with some additional set up required for ARM Macs:
Docker Desktop version 4.16.0 or later is required.

Use Rosetta for hardware emulation:

Open Docker Desktop’s Settings panel

Open the Features in development section.

Open the Beta features tab, and enable the setting Use Rosetta for x86/amd64 emulation on Apple Silicon.

We recommend changing the file sharing implementation to VirtioFS:

Open Docker Desktop’s Settings panel

Open the General section.

For the setting Choose file sharing implementation for your containers select VirtioFS.

Use the Apply & Restart button to save the change.

Restart the Docker Engine by clicking on the Docker icon in the menu bar and selecting Restart.
Use Rosetta for emulation, and we recommend changing the file sharing implementation to VirtioFS:

Open Rancher Desktop’s Preferences panel.

Open the Virtual Machine section.

Open the Emulation tab

Set Virtual Machine Type to VZ.

In the VZ suboption, enable Rosetta.

Open Volumes tab, and set the Mount Type to virtiofs.

Use the Apply button to save the changes.

In order to use the cuno-mac utility with Rancher, the “dockerd” (moby) container engine must be used:

Open Rancher Desktop’s Preferences panel.

Open the Container Engine section.

In the General tab, set the Container Engine to dockerd (moby).

Use the Apply button to save the change.
Usage of cunoFS on OrbStack for Mac containers works without any additonal set up required. OrbStack does not currently work with the native/host cuno-mac utility.
Download the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the Scripted Installer.
Install the package onto your Mac directly, or inside a Linux container:
Installing cunoFS on to your Mac directly will allow you to use cuno-mac, our handy tool for launching Linux containers that automatically have your local installation of cunoFS installed inside them.

Note

To use cuno-mac, you must also have Python 3 installed and available as python3 in Terminal.
1. In a Terminal on your Mac, navigate to your download directory. If this was the default Downloads folder, you can run:
  cd /Users/$USER/Downloads
2. Run the installer (without sudo):
  sh cuno-glibc-installer.run
3. Please follow the interactive steps, read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the installation.
4. Export the cuno-mac location to your PATH variable:
  export PATH=$PATH:~/.local/opt/cuno/share/macos
  To have this persist and apply to new Terminal sessions, add this as a new line at the bottom of the file /Users/<your username>/.bash_profile using a text editor, or using the following command in a Terminal session:
  echo "PATH=\$PATH:~/.local/opt/cuno/share/macos" >> ~/.bash_profile
  Warning
  
  Do not miss the \ because otherwise your current PATH will be written literally into the profile and break future changes.
If installing on your Mac’s local user is not preferred, you can install cunoFS within a container of your choice. We provide instructions here for installing within Docker containers using Ubuntu images. These instructions can be adapted to other Linux distributions, as well other virtualisation technologies such as Rancher, and OrbStack.

These instructions depend on the architecture of you Mac, please follow the appropriate guide:
Run the following command to run a Docker container with the cunoFS installer made available at /tmp/cuno_install:

Warning

This command will download the latest stable Ubuntu image, which could be large.

docker run -it --rm --entrypoint /bin/bash \ -v <path_to_installation_script>/cuno-glibc-installer:/tmp/cuno_install \ --name cuno-container \ ubuntu:latest

Within the Docker container (using docker exec -it cuno-container /bin/bash), install cunoFS:

sh /tmp/cuno_install

Please follow the interactive steps, read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the installation.
Run the following command to run a Docker container with the cunoFS installer made available at /tmp/cuno_install:

Warning

This command will download the latest stable Ubuntu image, which could be large.

docker run -it --rm --entrypoint /bin/bash \ -v <path_to_installation_script>:/tmp/cuno_install \ --name cuno-container \ --platform linux/amd64 ubuntu:latest

Note

The --platform linux/amd64 flag is required to run cunoFS on Macs with Apple Silicon.

Within the Docker container (using docker exec -it cuno-container /bin/bash), install cunoFS:

sh /tmp/cuno_install

Please follow the interactive steps, read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the installation.
The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

Licenses and activation#

When installing, you will have the option for a 14-day trial of cunoFS Professional. You don’t need to register or activate cunoFS during the trial period. To continue using cunoFS beyond the trial period, you must register online and activate your license.

Note

Trials are only to be used once per user/organisation. If installing inside a cloud instance or container, you should register and activate an appropriate license manually.

Register online for a free personal-use license or Professional, Educational or Enterprise evaluation. Contact sales@cuno.io when you’re ready for a quote.

All free licenses (including evaluations) let you use Professional-tier features for 14 days, and thereafter you will be limited to the Personal tier of usage. See the pricing page for more information about pricing, licenses and the available features on each tier.

Activating your license#

If you have registered, you can activate your license (sent to you via email) by running the following command and following the interactive steps:

cuno creds activate

Open Terminal, and run the command:

cuno-mac creds activate

Note

Instructions for cuno-mac users

If any arguments are given to cuno-mac, it starts a temporary container with your installation of cuno mounted into it, and runs the command inside the container.

The first time cuno-mac is run, a Docker container will be created with cunoFS ready to use and a user set up within the container similar to your local user on your Mac.

Testing your installation#

You should now be able to run cunoFS from the command line, which you can test out by running the following command:

cuno version

Note

If you have installed cunoFS directly onto a Mac, you must choose between using cuno-mac and cuno depending on the environment you are currently in.

If you’re in a Mac Terminal session and have not run cuno-mac, then you must replace cuno in any instructions with cuno-mac.

If you have already started a cunoFS container by calling cuno-mac, you will see the (cuno) prefix on your command line so any instructions using cuno commands will work as-is.

To return to macOS, run exit.

See Additional instructions for cuno-mac users for information.

Open Terminal and run:

cuno-mac version

If you have already started a cuno-mac session:

cuno version

To test that cunoFS is fully working before connecting your own object storage, you can use it to browse publicly available data. In the following example, we use cunoFS to browse space telescope data hosted on the stpubdata Amazon S3 bucket:

$ cuno run sh -c "ls s3://stpubdata/"

galex  hst  jwst  k2  kepler  panstarrs  tess

$ cuno run sh -c "ls s3://stpubdata/tess/public/*"

's3://stpubdata/tess/public/ffi':
s0001  s0005  s0009  s0013  s0017  s0021  s0025  s0029 ... [truncated]

's3://stpubdata/tess/public/mast':
tess-s0001-1-1-cube.fits  tess-s0012-1-4-cube.fits  tess-s0023-2-3-cube.fits ... [truncated]

... [truncated]

Note

Note that cuno run is a way to run a single command within a cunoFS context. Most of the time, and for interactive usage, we recommend starting a “wrapped” shell using the command cuno - see the Loading cunoFS section of this guide for more information, or the equivalent section from the full user guide for extra detail.

$ cuno-mac run sh -c "ls s3://stpubdata/"

galex  hst  jwst  k2  kepler  panstarrs  tess

$ cuno-mac run sh -c "ls s3://stpubdata/tess/public/*"

's3://stpubdata/tess/public/ffi':
s0001  s0005  s0009  s0013  s0017  s0021  s0025  s0029 ... [truncated]

's3://stpubdata/tess/public/mast':
tess-s0001-1-1-cube.fits  tess-s0012-1-4-cube.fits  tess-s0023-2-3-cube.fits ... [truncated]

... [truncated]

Note

Note that cuno-mac run is a way to run a single command within a cunoFS context. Most of the time, and for interactive usage, we recommend starting a container using the command cuno-mac and running your commands directly inside it - see the Loading cunoFS section of this guide for more information, or the equivalent section from the full user guide for extra detail.

Download, Installation and Activation

Contents

Download, Installation and Activation#

Downloading and installing#

Licenses and activation#

Activating your license#

Testing your installation#