{"id":42148159,"url":"https://github.com/peter-mount/fileserver","last_synced_at":"2026-01-26T18:01:07.157Z","repository":{"id":85760338,"uuid":"53536070","full_name":"peter-mount/fileserver","owner":"peter-mount","description":"A Docker based application utilising several of the projects here to provide a simple HTTP server based on the Java NIO-2 FileSystem API's","archived":false,"fork":false,"pushed_at":"2018-03-06T07:42:38.000Z","size":59,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-06T21:38:18.658Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/peter-mount.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2016-03-09T22:19:45.000Z","updated_at":"2016-03-10T00:08:55.000Z","dependencies_parsed_at":"2023-05-10T19:30:49.909Z","dependency_job_id":null,"html_url":"https://github.com/peter-mount/fileserver","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/peter-mount/fileserver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mount%2Ffileserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mount%2Ffileserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mount%2Ffileserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mount%2Ffileserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peter-mount","download_url":"https://codeload.github.com/peter-mount/fileserver/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mount%2Ffileserver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28784093,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T13:55:28.044Z","status":"ssl_error","status_checked_at":"2026-01-26T13:55:26.068Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-01-26T18:00:30.571Z","updated_at":"2026-01-26T18:01:07.141Z","avatar_url":"https://github.com/peter-mount.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# area51-fileserver\n\nA simple Docker enabled https server utilising our java nio [FileSystem](https://github.com/peter-mount/filesystem) and [HTTPD](https://github.com/peter-mount/httpd) components.\n\nCurrently it supports just serving content but (near) future versions will include:\n* ACL control of content\n* Write support\n* HTTPS support\n\n## Configuration\n\nThe image requires one configuration file in the etc directory (see CONFIGURATION_DIR below). This file is fileserver.json and defines the http server.\n```json\n{\n    \"filesystems\": [\"test\"],\n\n    \"filesystem\": {\n        \"test\": {\n            \"uri\":\"local://test\",\n            \"prefix\":\"test\"\n        }\n    }\n}\n```\n* filesystems is a json list of file system names, one for each file system to mount.\n* filesystem is a json object containing an object for each filesystem. A file system is optional here, you can also have it located in an external file - more later.\n\nEach file system consists of a minimum of two values:\n* uri - the FileSystem URI which will be used to mount the file system within Java NIO-2.\n* prefix - this is the path prefix exposed within the server. All files within the filesystem will be served from /prefix/ root on the server.\n\nSo in the example above the \"test\" filesystem will mount the URI \"local://test\" and all files within it will be served from `http://host:8080/test/` url (\n\n### HTTPD configuration\nThis is done within the \"httpd\" entry within the main json object. There's too many to write on this page but the main one is port (which defaults to 8080)\n```json\n{\n    \"filesystems\": [\"test\"],\n\n    \"httpd\": {\n        \"port\": 80\n    }\n}\n```\n\n### External FileSystem configuration\n\nYou don't have to put every file system into the core file. Instead you can create a .json file for each one using the filesystem's name. This file is placed under the filesystem subdirectory of the one containing fileserver.json and has the same structure as the object in the main file:\n\nFor example:\n```json\n{\n    \"filesystems\": [\"test\"],\n}\n```\n\nand filesystem/test.json:\n``` json\n{\n    \"uri\":\"local://test\",\n    \"prefix\":\"test\"\n}\n```\n\n## Docker Image\n\nThe image supports a few environment variables:\nEnvironment Variable | Default value | Purpose\n-------------------- | ------------- | -------\nCONFIGURATION_DIR | /opt/fileserver/etc | the location in the image of the configuration files\nFILESYSTEM_BASE | /opt/fileserver/data | the location in the image of where the filesystems are stored\nAWS_CREDENTIAL_PROFILES_FILE | /opt/fileserver/etc/.aws | the location of the AWS credentials. Only required if proxying S3 buckets.\nPREFER_IPv6_ADDRESSES | _not defined_ | Set if you want the fileserver to prefer IPv6 addresses when performing DNS lookups. This is the equivalent of passing -Djava.net.preferIPv6Addresses=true to the JVM.\nTIMEZONE | time zone of host | Set the timezone of the server\nRUNJDWP | _not defined_ | If set the port to listen for a debugger to attach. The server will not start until the debugger attaches if this is set\n\nTo be of any use you will need to mount the CONFIGURATION_DIR and FILESYSTEM_BASE directories to either directories on the host or to a docker volume container for the file server to be of any use. If you don't set those values then use the defaults\n\n**Note:** Here we use -p 8080:8080 to expose the server on the host. If you use direct routing to the container (which I do as I have each container with it's own Global IPv6 static address) you can leave that parameter out.\n### Run in the background using host directory mounts:\n```java\ndocker run -d \\\n    -v /path/fileserver/etc:/opt/fileserver/etc \\\n    -v /path/fileserver/etc:/opt/fileserver/filesystem \\\n    -p 8080:8080 \\\n    area51/fileserver\n```\n\n### Run on the console (useful in development):\n```java\ndocker run -it --rm \\\n    -v /path/fileserver/etc:/opt/fileserver/etc \\\n    -v /path/fileserver/etc:/opt/fileserver/filesystem \\\n    -p 8080:8080 \\\n    area51/fileserver\n```\nYou can ^C this to stop it.\n\n### Poking around\nIf you want to poke around the container, then you can use the following to get a shell:\n```java\ndocker run -it --rm \\\n    -v /path/fileserver/etc:/opt/fileserver/etc \\\n    -v /path/fileserver/etc:/opt/fileserver/filesystem \\\n    -p 8080:8080 \\\n    area51/fileserver \\\n    /bin/ash\n```\nWhen poking around to start the server run /opt/fileserver/fileserver and you can use ^C to stop and return to the ash shell. ^D to exit the container.\n\n## Advanced configuration\n\nAs an advanced configuration, here's how to create a simple Map Tile proxy to OpenStreetMap.\n\n```json\n{\n    \"filesystems\": [\"tiles\"],\n\n    \"filesystem\": {\n\t\"tiles\": {\n\t    \"name\":\"tiles\",\n\t    \"uri\":\"cache://tiles\",\n\t    \"prefix\":\"tiles\",\n\t    \"environment\": {\n\t\t\"fileSystemType\":\"cache\",\n\t\t\"remoteUrl\": \"http://c.tile.openstreetmap.org/\",\n\t\t\"fileSystemWrapper\": \"http\",\n\t\t\"maxAge\": 172800000,\n\t\t\"scanDelay\": 3600000,\n\t\t\"expireOnStartup\": true\n\t    }\n\t}\n    },\n}\n```\n\nNow running this and running wget against it:\n``` java\nwget http://127.0.0.1:8080/tiles/13/4107/2732.png -O 2732.png\n```\n\nYou end up with:\n![Maidstone](2732.png)\n\nNow once an hour (scanDelay) it will look for entries that are 2 days old (maxAge) and remove them. Until then it will serve it's local copy, so we only hit the remote server just once.\n\n## Proxying S3 buckets\n\nYou can now proxy a Amazon S3 bucket. This is simply a filesystem with an S3 bucket configured as the remote file store.\n\nThe minimum environment entries you need are: fileSystemWrapper set to s3read and bucket containing your bucket name. Like the previous example you can set the cache expiry settings. If an entry is expired then it will go back to S3 to retrieve the object.\n\n```json\n{\n    \"filesystems\": [\"bucket\"],\n\n    \"filesystem\": {\n\t\"bucket\": {\n\t    \"name\":\"bucket\",\n\t    \"uri\":\"cache://bucket\",\n\t    \"prefix\":\"bucket\",\n\t    \"environment\": {\n\t\t\"fileSystemWrapper\": \"s3read\",\n\t\t\"bucket\": \"my.bucket\"\n\t    }\n\t}\n    },\n}\n```\n\nYou also need to put your AWS credentials in the .aws file within the config directory.\n\nNow running this and running wget against it:\n``` java\nwget http://127.0.0.1:8080/bucket/someobject -O someobject\n```\n\nYou will then retrieve that object from Amazon S3, but it will now be cached locally. This is useful as it costs to retrieve an object from S3, so it can save you money by providing a local cache of regularly used objects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-mount%2Ffileserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeter-mount%2Ffileserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-mount%2Ffileserver/lists"}