{"id":15068902,"url":"https://github.com/jveverka/file-server","last_synced_at":"2025-04-10T16:51:26.718Z","repository":{"id":101222562,"uuid":"163414025","full_name":"jveverka/file-server","owner":"jveverka","description":"Simple file server providing REST APIs to access remote file system.","archived":false,"fork":false,"pushed_at":"2024-05-12T10:08:13.000Z","size":192,"stargazers_count":71,"open_issues_count":2,"forks_count":22,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-24T14:44:14.063Z","etag":null,"topics":["file-manager","file-sharing","file-system","file-upload","java11","jdk11","microservice","springboot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jveverka.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2018-12-28T13:33:40.000Z","updated_at":"2025-01-28T12:35:34.000Z","dependencies_parsed_at":"2024-10-13T03:40:54.753Z","dependency_job_id":"878104c7-252f-4feb-b6bf-0cf20a15e22a","html_url":"https://github.com/jveverka/file-server","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jveverka%2Ffile-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jveverka%2Ffile-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jveverka%2Ffile-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jveverka%2Ffile-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jveverka","download_url":"https://codeload.github.com/jveverka/file-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248255960,"owners_count":21073426,"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":["file-manager","file-sharing","file-system","file-upload","java11","jdk11","microservice","springboot"],"created_at":"2024-09-25T01:39:40.360Z","updated_at":"2025-04-10T16:51:26.691Z","avatar_url":"https://github.com/jveverka.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Java11](https://img.shields.io/badge/java-11-blue)](https://img.shields.io/badge/java-11-blue)\n[![Gradle](https://img.shields.io/badge/gradle-v7.2-blue)](https://img.shields.io/badge/gradle-v7.2-blue)\n![Build and Test](https://github.com/jveverka/file-server/workflows/Build%20and%20Test/badge.svg)\n\n# FileServer \nThis FileServer makes specified *base directory* accessible via REST APIs allowing you \nto list, download, upload, move and delete files and create empty directories. It also provides \nuser access control and security.\n\n![architecture](docs/architecture-01.svg)\n\n## Features implemented\n* Standalone java server, running on linux system.\n* Runs on the top of file system of host server.\n* Provides access via REST APIs to the file system.\n* File system operations supported\n  - list / read content of the directory\n  - download file, upload file\n  - create empty directory\n  - delete file or directory\n  - move file or directory\n  - get audit data for resource (file or directory) like number of downloads, uploads, ...\n* Uses Role based access control \n* Supports multi-tenancy (many users and roles)\n* Access for anonymous users (user not logged in) \n* Privileged admin role for server setup and monitoring\n* Transport protocols: http or https\n* Single jar distribution (~16MB).  \n* Admin APIs for monitoring and management access and users/roles.\n* Audit APIs for admin, to check activities on server.\n* Server setup is stored in memory or on file system.\n\n## Planned features\n* web UI / web client for REST APIs\n* compressed directory download\n* compressed directory upload\n\n## Configurations\nFileServer may be configured in several distinct ways. Check\n[configurations examples](docs/Configurations.md) chapter for more examples.\n\n## Requirements for developers\n* [JDK 11](https://jdk.java.net/11/) or later (JDK 8 is supported as well)\n* [Gradle 7.2](https://gradle.org/install/) or later\n\n## Runtime requirements\n* [JDK 11](https://jdk.java.net/11/) or later (JDK 8 is supported as well)\n* Requires read/write access to *base directory* on local file system.\n\n### Rest Endpoints\nAll REST endpoints use 'dynamic' path. This means that path ``**`` is used as relative path in *base directory*.\nSee also [postman collection example](docs/FileServer.postman_collection.json).\n\n#### Get list of files  \n* __GET__ http://localhost:8888/services/files/list/** - list content directory or subdirectory  \n  ``curl -X GET http://localhost:8888/services/files/list/ -b /tmp/cookies.txt``\n\n#### Download file  \n* __GET__ http://localhost:8888/services/files/download/** - download file on path. file must exist.   \n  ``curl -X GET http://localhost:8888/services/files/download/path/to/001-data.txt -b /tmp/cookies.txt``\n\n#### Upload file\n* __POST__ http://localhost:8888/services/files/upload/** - upload file, parent directory(ies) must exist before upload  \n ``curl -F 'file=@/local/path/to/file.txt' http://localhost:8888/services/files/upload/path/to/001-data.txt -b /tmp/cookies.txt``\n\n#### Delete files and/or directories\n* __DELETE__ http://localhost:8888/services/files/delete/** - delete file or directory  \n  ``curl -X DELETE http://localhost:8888/services/files/delete/path/to/001-data.txt -b /tmp/cookies.txt``\n\n#### Create empty directory\n* __POST__ http://localhost:8888/services/files/createdir/** - create empty directory  \n  ``curl -X POST http://localhost:8888/services/files/createdir/path/to/directory -b /tmp/cookies.txt``\n\n#### Move file or directory\n* __POST__ http://localhost:8888/services/files/move/** - move file or directory. If source is file, destination must be also a file, If source is directory, destination must be directory as well.\n  ``curl -X POST http://localhost:8888/services/files/move/path/to/source -b /tmp/cookies.txt -d '{ \"destinationPath\": \"path/to/destination\" }''``\n\n#### Get audit data\n* __GET__ http://localhost:8888/services/files/audit/** - get audit data for the resource.\n  ``curl -X GET http://localhost:8888/services/files/audit/path/to/source -b /tmp/cookies.txt``\n\n### Security\nIn order to use file server REST endpoints above, user's http session must be authorized.\nUsers have defined their roles and access rights to files and directories. \nSee this [example](src/main/resources/application.yml) of server configuration.\n\n#### login\n* __POST__ http://localhost:8888/services/auth/login  \n  ``curl -X POST http://localhost:8888/services/auth/login -H \"Content-Type: application/json\" -d '{ \"userName\": \"master\", \"password\": \"secret\" }' -c /tmp/cookies.txt``\n\n#### logout\n* __GET__ http://localhost:8888/services/auth/logout  \n  ``curl -X GET http://localhost:8888/services/auth/logout -b /tmp/cookies.txt``\n\n### Admin access\nSelected role ``fileserver.admin.role`` is used for admin access. Users with this role have access to special dedicated REST endpoints.\nSee this [example](src/main/resources/application.yml) of server configuration.\nRefer to [attached postman collection](docs/FileServer.postman_collection.json) for all admin APIs.\n\n#### Implemented admin features\n* get volume information - base directory, used and free space\n* get all open/active user sessions\n* terminate selected user's session\n* user management\n  - get name of admin role\n  - get name of anonymous role\n  - list all users\n  - create new user\n  - remove user\n* file access filter management\n  - list all access filters\n  - create new access filter\n  - remove existing access filter\n* audit data querying showing activities like:\n  - login / logout events\n  - file access events (download, upload, delete, ... all events are recorded)\n  - user management events\n  - file access filter management events  \n\n### Run in Docker\n* Run with default configuration [application.yml](src/main/resources/application.yml) - only for demo purposes.\n  ```\n  docker run -d --name file-server-1.3.0 \\\n    --restart unless-stopped \\\n    -e SERVER_PORT=8888 \\\n    -p 8888:8888 jurajveverka/file-server:1.3.0\n  ```\n* Run with custom configuration. Note that customized ``application.yml`` is located at ``${FS_CONFIG_DIR}/application.yml``\n  and ``fileserver.home`` points to ``/opt/data/files``\n  ```\n  docker run -d --name file-server-1.3.0 \\\n    --restart unless-stopped \\\n    -e SERVER_PORT=8888 \\\n    -e APP_CONFIG_PATH=/opt/data/config/application.yml \\\n    -v '${FS_CONFIG_DIR}':/opt/data/config \\\n    -v '${FS_FILES_DIR}':/opt/data/files \\\n    -p 8888:8888 jurajveverka/file-server:1.3.0\n  ```\n* Build your own [docker image for amd64 or arm64v8](docs/DockerBuild.md) platform.\n\n### Build and Run\nVariable ``fileserver.home`` in ``application.yml`` file defines *base directory* to be exposed via REST APIs.\n```\ngradle clean build test\njava -jar build/libs/file-server-1.3.0-SNAPSHOT.jar --spring.config.location=file:./src/main/resources/application.yml\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjveverka%2Ffile-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjveverka%2Ffile-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjveverka%2Ffile-server/lists"}