Getting Started

Note: This is a quick start guide written for JuiceFS Hosted Service. If you just want to learn about the usage of the community version of JuiceFS client, please check Community Edition Document.

System Requirement

Operating System: JuiceFS supports Linux, macOS and Windows. It is compatible with POSIX through FUSE. Please make sure that FUSE has been installed before use. Most Linux distributions have built-in FUSE modules. For macOS, it is recommended to install macFUSE to support FUSE. Windows recommends installing WinFsp to support FUSE.
Storage: With JuiceFS, all data will be stored in your own object storage. You can manually create an object storage bucket on the cloud platform, or let the JuiceFS hosted service automatically create an object storage bucket for you. No matter which method you use, you need to prepare the key to access the object storage API .
Python: JuiceFS hosted service relies on the Python environment. Please check you has Python 2.5+ or Python 3.x installed.

Create a Filesystem

JuiceFS hosted service needs to create a filesystem through the official website console. New users should first complete the registration on the JuiceFS website. Then log in to your console and click the \"Create\" button.

Note: When creating a filesystem, Region is used to specify the service provider and region where your object storage is located. When you mount a filesystem, if the object storage does not exist, JuiceFS will create the object storage bucket under your cloud platform according to your settings. At the same time, the closest official metadata storage cluster will be matched for you.
If the cloud service provider or region you want to choose is not in the list, please submit an application according to the prompt information. Our engineers will support the required platform within 72 hours and the required region within 24 hours.

If you want to use the existing object storage, please check \"Advanced Options\" and fill in the bucket name. In addition, you can also adjust the \"Block Size\" and \"Compression\" algorithm of the filesystem.

After the filesystem is created, the page will redirect. Then you can follow the prompts on the page to mount the filesystem to your server.

There is a bold display Token in the help description. When you mount the filesystem, you need to use this Token to verify your identity. Each filesystem you create will generate a unique token.

Note: You can create as many filesystems as you need. When creating a filesystem, you can either assign the created object storage bucket to the filesystem, or let JuiceFS automatically create an object storage bucket on your cloud platform. In short, with JuiceFS, all data must be stored in your own object storage.

Installation

The hosted service provides a JuiceFS client based on the Python language, which simplifies the connection between the JuiceFS client and the official metadata cluster, allowing you to mount the filesystem simply and quickly. Before installation and use, please make sure you have installed Python 2.5+ or Python 3.x.

Refer to the prompt of the official website console and execute the following command to download the client:

$ curl -L https://juicefs.com/static/juicefs -o juicefs && chmod +x juicefs

Attention: The JuiceFS client control program is essentially a script program that controls the JuiceFS open source client. For ease of use, the control program is named juicefs. If you want to use the JuiceFS client and the control program provided by the hosted service at the same time, because the names of the two will conflict, it is recommended to modify the name of the control program, for example: juicefs-ctl.

Execute the client, if you see the help message returned, that means the client is installed successfully.

$ ./juicefs

juicefs COMMAND [options]

COMMAND could be:
auth      authorize a filesystem
mount     mount a filesystem
umount    umount a filesystem
info      show information of file or directory
lsof      list recent opened files
import    import files from existing object storage
rmr       remove all files/directories recursively
snapshot  create or remove snapshots
grep      parallelized file pattern searcher
profile   analyze log (Experimental)
benchmark run benchmark
warmup    build cache for target directories/files
version   show the version

Mount a filesystem

Mount in CLI

Refer to the following format to mount the filesystem, please replace NAME-OF-JUICEFS with the actual filesystem name:

$ sudo ./juicefs mount NAME-OF-JUICEFS /jfs

When the filesystem is mounted for the first time, the JuiceFS client will interactively ask you for a series of information. For example, the following command will mount the filesystem quick to the /jfs directory, and it will ask for the token of the filesystem, And the \"Access Key ID\" and \"Access Key Secret\" required to access the object storage API.

$ sudo ./juicefs mount quick /jfs
Token for quick: 4bc1xxxxxxxxx9591dec66
Access key ID for oss://juicefs-quick: LTxxxxxxxxxxxxVWL
Access key secret for oss://juicefs-quick: Xl7DpxxxxxxxxxxxxxxxDMhfUUa
OK, quick is ready at /jfs.

Tips: Only when you mount the filesystem on a host for the first time, you need to provide secret key information such as Token. After the mount is successful, these secret key information will be saved in a configuration file in the current user\'s $HOME/.juicefs directory. After that, you no longer need to provide it manually when mounting, and the client will automatically read them from the configuration file. The Token of the filesystem can be found in the official website console, and the API access key for object storage can be obtained by this document.

Note: The object storage API access secret key you provide must have the permission to create an object storage bucket on the cloud platform you specify.

If you use macOS, you can mount with the following command:

$ ./juicefs mount NAME-OF-JUICEFS ~/jfs

After successfully mounting, the juicefs client will run in the background, and all logs will be recorded in syslog (Facility: LOG_USER).

Remember the token and keys

Instead of typing the token and keys interactively, they could be remembered by using juicefs auth before mounting (automated by scripts):

$ sudo ./juicefs auth --token TOKEN --accesskey ACCESSKEY --secretkey SECRETKEY NAME
$ sudo ./juicefs mount NAME-OF-JUICEFS MOUNTPONT

And you could put them in a JSON file $HOME/.juicefs/NAME.conf like:

{"token": TOKEN, "accesskey": ACCESSKEY, "secretkey": SECRETKEY}

Mount on boot

Linux

After copy juicefs as /sbin/mount.juicefs, you could mount JuiceFS using the mountcommand (use juicefs auth to remember the keys first):

$ mount -t juicefs  NAME-OF-JUICEFS /jfs

You could also add it to /etc/fstab, so it could be mounted after reboot:

NAME-OF-JUICEFS   /jfs     juicefs    _netdev   0 0

For more details on these commands, please check the help message of each command.

Note: By default, CentOS 6 will NOT mount network filesystem after boot, run the following command to enable it:

$ sudo chkconfig --add netfs

macOS

In the following description, some variables will be used to refer to the values that should be filled in. Please substitute it to the corresponding value:

NAME file system name
PATH_TO_JUICEFS juicefs path（E.g.: /usr/local/bin/juicefs）
MOUNTPOINT mount path

Refer to unmount_filesystem{.interpreted-text role="ref"} to ensure that the target mount path is unmounted
Refer to remember_authentication{.interpreted-text role="ref"} to save authorization information in a local file

Create a file com.juicefs.NAME.plist under ~/Library/LaunchAgents:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>Label</key>
        <string>com.juicefs.NAME</string>
        <key>ProgramArguments</key>
        <array>
                <string>PATH_TO_JUICEFS</string>
                <string>mount</string>
                <string>NAME</string>
                <string>MOUNTPOINT</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
</dict>
</plist>

Load the file created in the previous step and test whether the loading is successful:

launchctl load ~/Library/LaunchAgents/com.juicefs.NAME.plist
launchctl start ~/Library/LaunchAgents/com.juicefs.NAME
ls MOUNTPOINT

If the mount is failed, you can add the following configuration to the plist file above:

<key>StandardErrorPath</key>
<string>/tmp/mycommand.err</string>
<key>StandardOutPath</key>
<string>/tmp/mycommand.out</string>

Use the following commands to reload the latest configuration and inspect the output:

launchctl unload ~/Library/LaunchAgents/com.juicefs.NAME.plist
launchctl load ~/Library/LaunchAgents/com.juicefs.NAME.plist
cat /tmp/mycommand.out
cat /tmp/mycommand.err

Mount JuiceFS from Docker container

JuiceFS could be mounted inside Docker (or other containers), require the permission to access FUSE device from the container, which could be granted while launching the Docker with these options:

docker run --cap-add SYS_ADMIN --device=/dev/fuse --security-opt apparmor:unconfined

Import existing objects

For the files that are already in object storage, can be easily imported into JuiceFS, to have all the benefits of JuiceFS without moving or copying them.

They could be imported like this:

$ sudo ./juicefs import BUCKET-NAME/PREFIX TARGET-DIR-IN-JUICEFS

For example, the following command could import all the files in my-bucket with prefix my-files into a directory my-files in JuiceFS:

$ sudo ./juicefs import my-bucket/my-files /jfs/my-files

It will only load the metadata into JuiceFS, the files are still in object storage, you can access them as usual. After importing, you can change the attributes of files (including renaming) just like they are created in JuiceFS, these change will NOT sync back into object storage, deleting an imported file in JuiceFS will NOT delete the underlying file in object storage.

Note: The same key pair is used to access imported files, please make sure that the key has read permission on the imported bucket.

Create a Snapshot

A snapshot is a data copy created from the state of a directory or file at a certain point in time. This is a very meaningful data backup and protection mechanism. Create a snapshot before critical operations. Once a failure occurs, you can use the snapshot to restore the data to the state when the snapshot was created.

JuiceFS supports atomic snapshot, you could make a copy of file or directory instantly. The snapshot reuses the underlying data blocks, only the blocks that are modified later will be copied.

A snapshot could be created like this:

$ ./juicefs snapshot SRC DST

Note: Snapshots can only be created for files or folders on the JuiceFS filesystem, and snapshots can only be saved in the filesystem where the source file is located.

You could also remove the whole snapshot quickly by:

$ ./juicefs snapshot -d DST

Note: ./juicefs snapshot -d can only remove the snapshot. Otherwise, it will say \"Operation not permitted\".

Unmount

Warning: Unmounting an in-use filesystem is risky, it may result in data loss. Before performing the operation, please make sure that you have backed up important data.

Use the umount command to umount a filesystem:

$ sudo umount /jfs

If the command prompts umount: /jfs: target is busy., it indicates that the filesystem is in use. It is recommended to use lsof MOUNTPOINT to find and terminate the related application process before performing.

For Linux, you can use the -l option to perform delayed umount (the file system is immediately unmounted, but the resources will not be cleaned up until the device is no longer busy):

$ sudo umount /jfs -l

For macOS, you can use the force option to force umount:

$ sudo diskutil unmount force /jfs

Then you can manually kill the juicefs process, or you can wait for it to exit by itself.

Delete a filesystem

If you need to delete a filesystem created in the hosted service, for data security considerations, you should strictly follow the following steps when deleting:

Backup all data in the filesystem;
Delete all the files and empty the trash;
Unmount the filesystem on the host;
Delete the filesystem in the official website console;
Find and delete the configuration file of the filesystem in the $HOME/.juicefs directory of the host, usually named in the form of <YOUR-FS-NAME>.conf.

System Requirement ​

Create a Filesystem ​

Installation ​

Mount a filesystem ​

Mount in CLI ​

Remember the token and keys ​

Mount on boot ​

Linux​

macOS​

Mount JuiceFS from Docker container​

Import existing objects ​

Create a Snapshot ​

Unmount ​

Delete a filesystem ​