Quick start

Run a single reva server with Docker, log in, and upload a file over WebDAV and with the reva CLI.

This guide starts one revad process that holds all the services for a small setup. It stores files on the local disk and reads users from a JSON file. Use it to learn reva, not in production.

You need Docker (or Podman) and curl.

1. Write the configuration

Make a folder and save these two files in it.

revad.toml

# One revad process with everything needed to log in and manage files.

[shared]
jwt_secret = "change-me"
gatewaysvc = "localhost:19000"

[grpc]
address = "0.0.0.0:19000"

[grpc.services.gateway]
authregistrysvc = "localhost:19000"
storageregistrysvc = "localhost:19000"
userprovidersvc = "localhost:19000"
transfer_shared_secret = "change-me-too"

[grpc.services.authregistry]
driver = "static"
[grpc.services.authregistry.drivers.static.rules]
basic = "localhost:19000"

[grpc.services.authprovider]
auth_manager = "json"
[grpc.services.authprovider.auth_managers.json]
users = "/etc/revad/users.json"

[grpc.services.userprovider]
driver = "json"
[grpc.services.userprovider.drivers.json]
users = "/etc/revad/users.json"

[grpc.services.storageregistry]
driver = "static"
[grpc.services.storageregistry.drivers.static]
home_provider = "/home"
[grpc.services.storageregistry.drivers.static.rules]
"/home" = { address = "localhost:19000" }

[grpc.services.storageprovider]
driver = "localhome"
mount_path = "/home"
mount_id = "home"
space_depth = 1
[grpc.services.storageprovider.drivers.localhome]
root = "/var/tmp/reva/data"

[http]
address = "0.0.0.0:19001"

[http.services.datagateway]
transfer_shared_secret = "change-me-too"
# The address clients use to send and fetch file data.
public_url = "http://localhost:19001/datagateway"

[http.services.dataprovider]
driver = "localhome"
mount_id = "home"
[http.services.dataprovider.drivers.localhome]
root = "/var/tmp/reva/data"

[http.services.ocdav]
webdav_namespace = "/home"

users.json

[
  {
    "id": { "opaque_id": "4c510ada-c86b-4815-8820-42cdf82c3d51", "idp": "localhost", "type": 1 },
    "username": "einstein",
    "secret": "relativity",
    "mail": "einstein@example.org",
    "display_name": "Albert Einstein",
    "uid_number": 1000,
    "gid_number": 1000
  }
]

The configuration enables these services. Each name links to its reference page.

TableWhat it does
gatewayReceives all CS3 API calls and routes them.
authregistry, authproviderCheck passwords with the json auth manager.
userproviderLooks up users with the json user manager.
storageregistry, storageproviderServe each user’s home folder with the localhome driver.
datagateway, dataproviderMove file data in and out of the storage.
ocdavServes WebDAV.

2. Start the server

Run this command in the folder with the two files:

docker run --rm --name reva \
  -p 19000:19000 -p 19001:19001 \
  -v "$PWD/revad.toml:/etc/revad/revad.toml:ro" \
  -v "$PWD/users.json:/etc/revad/users.json:ro" \
  cs3org/revad:v3.15.3

Port 19000 is gRPC (the gateway). Port 19001 is HTTP (WebDAV and data transfers). The log shows http server listening and grpc server listening when the server is ready.

On SELinux hosts, such as Fedora or RHEL, add ,Z after ro in both -v options.

3. Use WebDAV

Upload a file as the user einstein, then read it back and list the home folder:

echo "hello reva" > hello.txt
curl -u einstein:relativity -T hello.txt http://localhost:19001/remote.php/webdav/hello.txt
curl -u einstein:relativity http://localhost:19001/remote.php/webdav/hello.txt
curl -u einstein:relativity -X PROPFIND -H "Depth: 1" http://localhost:19001/remote.php/webdav/

The first command returns HTTP 201. The file is now in the container, under /var/tmp/reva/data.

Any WebDAV client can connect to http://localhost:19001/remote.php/webdav/ with the same user name and password.

4. Use the reva CLI

The reva command line client talks to the gateway over gRPC. Download it from the release page. For Linux on x86-64:

curl -Lo reva https://github.com/cs3org/reva/releases/download/v3.15.3/reva_v3.15.3_linux_amd64
chmod +x reva

Log in, then work with files. The --insecure flag is necessary because this server does not use TLS.

./reva config set host localhost:19000
echo relativity | ./reva --insecure login --username einstein basic
./reva --insecure whoami
./reva --insecure ls /home
./reva --insecure upload hello.txt /home/notes.txt
./reva --insecure download /home/notes.txt copy.txt

Run ./reva --help to see all commands, such as share, public-share, and versions.

5. Stop the server

docker stop reva

The container is removed when it stops, together with the uploaded files.

Run without Docker

Download revad from the release page, or build it:

git clone https://github.com/cs3org/reva
cd reva
make revad

Change /etc/revad/users.json in revad.toml to the path of your users.json, then start it:

./cmd/revad/revad -c revad.toml

Use revad -t -c revad.toml to check a configuration without starting the server.

Next steps