{"id":18677370,"url":"https://github.com/krotik/rufs","last_synced_at":"2025-04-12T02:38:40.920Z","repository":{"id":82003341,"uuid":"207092571","full_name":"krotik/rufs","owner":"krotik","description":"A remote union filesystem.","archived":false,"fork":false,"pushed_at":"2019-09-08T09:56:36.000Z","size":320,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T02:38:35.590Z","etag":null,"topics":["client","file-sharing","server","union-file-system"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/krotik.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-08T09:54:10.000Z","updated_at":"2022-10-04T06:07:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"0cee11ee-3910-47a2-b633-5475b992b8c0","html_url":"https://github.com/krotik/rufs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krotik%2Frufs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krotik%2Frufs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krotik%2Frufs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krotik%2Frufs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krotik","download_url":"https://codeload.github.com/krotik/rufs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248507173,"owners_count":21115551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","file-sharing","server","union-file-system"],"created_at":"2024-11-07T09:33:39.925Z","updated_at":"2025-04-12T02:38:40.913Z","avatar_url":"https://github.com/krotik.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"Rufs\n====\nRufs is a remote union filesystem which aims to provide a lightweight and secure solution for distributed file storage. Rufs uses a client-server system where servers expose branches and clients mount one or several branches into a tree structure. The client can overlay branches providing a union view.\n\n\u003cp\u003e\n\u003ca href=\"https://void.devt.de/pub/rufs/coverage.txt\"\u003e\u003cimg src=\"https://void.devt.de/pub/rufs/test_result.svg\" alt=\"Code coverage\"\u003e\u003c/a\u003e\n\u003ca href=\"https://goreportcard.com/report/devt.de/krotik/rufs\"\u003e\n\u003cimg src=\"https://goreportcard.com/badge/devt.de/krotik/rufs?style=flat-square\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n\u003ca href=\"https://godoc.org/devt.de/krotik/rufs\"\u003e\n\u003cimg src=\"https://godoc.org/devt.de/krotik/rufs?status.svg\" alt=\"Go Doc\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nFeatures\n--------\n- Client-Server model using RPC call over SSL.\n- Single executable for client and server.\n- Communication is secured via a secret token which is never transferred over the network and certificate pinning once a client has connected successfully.\n- Clients can provide a unified view with files from different locations.\n- Default client provides CLI, REST API and a web interface.\n- Branches can be read-only.\n- A read-only version of the file system can be exported via FUSE and mounted.\n\nGetting Started\n---------------\nYou can download a pre-compiled package for Windows (win64) or Linux (amd64) [here](https://void.devt.de/pub/rufs).\n\nThe archive contains a single executable which contains the server and client code for Rufs.\n\nYou can also pull the latest docker image of Rufs from [Dockerhub](https://hub.docker.com/r/krotik/rufs):\n```\ndocker pull krotik/rufs\n```\n\nCreate an empty directory, change into it and run the following to start the server:\n```\ndocker run --rm --user $(id -u):$(id -g) -v $PWD:/data -p 9020:9020 krotik/rufs server\n```\nThis exposes port 9020 from the container on the local machine. All runtime related files are written to the current directory as the current user/group.\n\nRun the client by running:\n```\ndocker run --rm --network=\"host\" -it -v $PWD:/data --user $(id -u):$(id -g) -v $PWD:/data krotik/rufs client\n```\nThe client will also use the runtime related files from the current directory.\n\n### Tutorial:\n\nTo get an idea of what Rufs is about have a look at the [tutorial](https://devt.de/krotik/rufs/src/master/examples/tutorial/doc/tutorial.md).\n\n### REST API:\n\nThe terminal uses a REST API to communicate with the backend. The REST API can be browsed using a dynamically generated swagger.json definition (https://localhost:9090/fs/swagger.json). You can browse the API of Rufs's latest version [here](http://petstore.swagger.io/?url=https://devt.de/krotik/rufs/raw/master/swagger.json).\n\n### Command line options\nThe main Rufs executable has two main tools:\n```\nRufs 1.0.0\n\nUsage of ./rufs [tool]\n\nThe tools are:\n\n    server    Run as a server\n    client    Run as a client\n\nUse ./rufs [tool] --help for more information about a tool.\n```\nThe most important one is `server` which starts the file server. The server has several options:\n```\nRufs 1.0.0\n\nUsage of ./rufs server [options]\n\n  -config string\n    \tServer configuration file (default \"rufs.server.json\")\n  -help\n    \tShow this help message\n  -secret string\n    \tSecret file containing the secret token (default \"rufs.secret\")\n  -ssl-dir string\n    \tDirectory containing the ssl key.pem and cert.pem files (default \"ssl\")\n\nThe server will automatically create a default config file and\ndefault directories if nothing is specified.\n```\nOnce the server is started the client tool can be used to interact with the server. The options of the client tool are:\n```\nRufs 1.0.0\n\nUsage of ./rufs client [mapping file]\n\n  -fuse-mount string\n    \tMount tree as FUSE filesystem at specified path (read-only)\n  -help\n    \tShow this help message\n  -secret string\n    \tSecret file containing the secret token (default \"rufs.secret\")\n  -ssl-dir string\n    \tDirectory containing the ssl key.pem and cert.pem files (default \"ssl\")\n  -web string\n    \tExport the tree through a https interface on the specified host:port\n\nThe mapping file assignes remote branches to the local tree.\nThe client tries to load rufs.mapping.json if no mapping file is defined.\nIt starts empty if no mapping file exists. The mapping file\nshould have the following json format:\n\n{\n  \"branches\" : [\n    {\n      \"branch\"      : \u003cbranch name\u003e,\n      \"rpc\"         : \u003crpc interface\u003e,\n      \"fingerprint\" : \u003cfingerprint\u003e\n    },\n    ...\n  ],\n  \"tree\" : [\n    {\n      \"path\"      : \u003cpath\u003e,\n      \"branch\"    : \u003cbranch name\u003e,\n      \"writeable\" : \u003cwritable flag\u003e\n    },\n    ...\n  ]\n}\n```\nOn the console type `q` to exit and `help` to get an overview of available commands:\n```\nAvailable commands:\n----\nbranch [branch name] [rpc] [fingerprint] : List all known branches or add a new branch to the tree\ncat \u003cfile\u003e                               : Read and print the contents of a file\ncd [path]                                : Show or change the current directory\nchecksum [path] [glob]                   : Show a directory listing and file checksums\ncp \u003csrc file/dir\u003e \u003cdst dir\u003e              : Copy a file or directory\ndir [path] [glob]                        : Show a directory listing\nget \u003csrc file\u003e [dst local file]          : Retrieve a file and store it locally (in the current directory)\nhelp [cmd]                               : Show general or command specific help\nmkdir \u003cdir\u003e                              : Create a new directory\nmount [path] [branch name] [ro]          : List all mount points or add a new mount point to the tree\nping \u003cbranch name\u003e [rpc]                 : Ping a remote branch\nput [src local file] [dst file]          : Read a local file and store it\nrefresh                                  : Refreshes all known branches and reconnect if possible.\nren \u003cfile\u003e \u003cnewfile\u003e                     : Rename a file or directory\nreset [mounts|brances]                   : Remove all mounts or all mounts and all branches\nrm \u003cfile\u003e                                : Delete a file or directory (* all files; ** all files/recursive)\nstoreconfig [local file]                 : Store the current tree mapping in a local file\nsync \u003csrc dir\u003e \u003cdst dir\u003e                 : Make sure dst has the same files and directories as src\ntree [path] [glob]                       : Show the listing of a directory and its subdirectories\n```\n\n### Configuration\nThe Rufs client and server use each their own configuration file and require a shared `rufs.secret` file to be able to talk to each other. The server configuration is called `rufs.server.json`. After starting the server for the first time it should create a default configuration file. Available configurations are:\n\n| Configuration Option | Description |\n| --- | --- |\n| BranchName | Branch name which the server will export. |\n| EnableReadOnly | Export the branch only for read operations. |\n| LocalFolder | Local physical folder which is exported. |\n| RPCHost | RPC host for communication with clients. |\n| RPCPort | RPC port for communication with clients. |\n\nNote: It is not (and will never be) possible to access the REST API via HTTP.\n\nBuilding Rufs\n----------------\nTo build Rufs from source you need to have Go installed (go \u003e= 1.12):\n\nCreate a directory, change into it and run:\n```\ngit clone https://devt.de/krotik/rufs/ .\n```\n\nYou can build Rufs's executable with:\n```\ngo build -o rufs ./cli/...\n```\n\nRufs also has a web interface which should be bundled with the executable. The bundled web interface in `web.zip` can be attached by running:\n```\n./attach_webzip.sh\n```\nThis assumes that the `rufs` executable is in the same folder as the script.\n\nBuilding Rufs as Docker image\n--------------------------------\nRufs can be build as a secure and compact Docker image.\n\n- Create a directory, change into it and run:\n```\ngit clone https://devt.de/krotik/rufs/ .\n```\n\n- You can now build the Docker image with:\n```\ndocker build --tag krotik/rufs .\n```\n\nLicense\n-------\nRufs source code is available under the [MIT License](/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrotik%2Frufs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrotik%2Frufs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrotik%2Frufs/lists"}