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.
# 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"
[
{
"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.
| Table | What it does |
|---|---|
gateway | Receives all CS3 API calls and routes them. |
authregistry, authprovider | Check passwords with the json auth manager. |
userprovider | Looks up users with the json user manager. |
storageregistry, storageprovider | Serve each user’s home folder with the localhome driver. |
datagateway, dataprovider | Move file data in and out of the storage. |
ocdav | Serves 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
- Read the architecture to see how the services work together.
- Read configuration to split services across processes.
- Replace the drivers: EOS or CephFS for storage, LDAP or OIDC for login.