{"id":13554173,"url":"https://github.com/remotestorage/armadietto","last_synced_at":"2025-05-07T13:05:36.281Z","repository":{"id":30799911,"uuid":"126025933","full_name":"remotestorage/armadietto","owner":"remotestorage","description":"RS server based on node.js","archived":false,"fork":false,"pushed_at":"2025-05-04T20:21:53.000Z","size":2581,"stargazers_count":103,"open_issues_count":13,"forks_count":13,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-07T13:05:29.536Z","etag":null,"topics":["nodejs","remotestorage","remotestorage-server"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/remotestorage.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2018-03-20T13:58:41.000Z","updated_at":"2025-04-30T04:23:30.000Z","dependencies_parsed_at":"2025-05-01T19:32:05.745Z","dependency_job_id":"550d825b-45bd-447a-842e-7b992d9b55d2","html_url":"https://github.com/remotestorage/armadietto","commit_stats":{"total_commits":507,"total_committers":15,"mean_commits":33.8,"dds":0.4556213017751479,"last_synced_commit":"75cf0a376e670228a8008cabb020e419a5a03e0d"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remotestorage%2Farmadietto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remotestorage%2Farmadietto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remotestorage%2Farmadietto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remotestorage%2Farmadietto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/remotestorage","download_url":"https://codeload.github.com/remotestorage/armadietto/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252883210,"owners_count":21819160,"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":["nodejs","remotestorage","remotestorage-server"],"created_at":"2024-08-01T12:02:41.246Z","updated_at":"2025-05-07T13:05:36.271Z","avatar_url":"https://github.com/remotestorage.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","nodejs"],"sub_categories":[],"readme":"# Armadietto [![npm](https://img.shields.io/npm/v/armadietto)](https://www.npmjs.com/package/armadietto) [![Build Status](https://github.com/remotestorage/armadietto/actions/workflows/test-and-lint.yml/badge.svg)](https://github.com/remotestorage/armadietto/actions/workflows/test-and-lint.yml?query=branch%3Amaster)\n\n\u003e ### :warning: WARNING\n\u003e Please do not consider `armadietto` production ready, this project is still\n\u003e considered experimental.  As with any alpha-stage storage technology, you\n\u003e MUST expect that it will eat your data and take precautions against this. You\n\u003e SHOULD expect that its APIs and storage schemas will change before it is\n\u003e labelled stable.\n\n## What is this?\n\nArmadietto is a [RemoteStorage](https://remotestorage.io) server written for Node.js.\n\nThis is a complete rewrite of [reStore](https://github.com/jcoglan/restore).\n\n## Containerized Installation, Usage \u0026 Development\n\nSee [the Docker README](./docker/README.md)\n\n## Installation (non-containerized)\n\n1. Ensure you have [a maintained version of Node](https://nodejs.org/en/about/releases/) installed.\n2. If you will be using Apache as a reverse proxy, ensure it is [version 2.4.49 or later](https://community.remotestorage.io/t/avoid-apache-as-a-basis-for-your-server/139).\n3. Run `npm -g i armadietto`\n\n\n## Usage\n\nSee the `notes` directory for configuring a reverse proxy and other recipes.\n\n### Modular (new) Server\n\n* Streaming storage (documents don't have to fit in server memory)\n* S3-compatible storage (requires separate S3 server; AWS S3 allows documents up to 5 TB)\n* Can run multiple application servers to increase capacity to enterprise-scale\n* Bug Fix: correctly handles If-None-Match with ETag\n* Bug Fix: returns empty listing for nonexistent folder\n* Implements current spec: draft-dejong-remotestorage-22\n\nSee [the modular-server-specific documentation](./notes/modular-server.md) for usage.\n\n### Monolithic (old) Server\n\n* Stores user documents in server file system\n* More thoroughly tested\n* Implements older spec: draft-dejong-remotestorage-01\n\nSee [the monolithic-server-specific documentation](./notes/monolithic-server.md) for usage.\n\n## Storage security\n\nIn production, we recommend that you restrict access to the files managed by\nyour armadietto server as much as possible. This is particularly true if you host\nyour storage on a machine with other web applications; you need to protect your\nfiles in the event that one of those apps is exploited.\n\nYou should take these steps to keep your storage safe:\n\n* Pick a unique Unix user to run your server process; no other process on the\n  box should run as this user:\n  `sudo useradd armadietto --system --no-create-home`\n\n* Do not run other applications as root, or as any user that could access files\n  owned by your armadietto user\n* Make sure the directory `path/to/storage` cannot be read, written or executed\n  by anyone but this user:\n  `sudo chmod 0700 /path/to/storage \u0026\u0026 sudo chown armadietto:armadietto /path/to/storage`\n\n* Do not run armadietto as root; if you need to bind to port 80 or 443 use a\n  reverse proxy like nginx, Apache2, caddy, lighttpd or enable bind capability:\n  ```setcap 'cap_net_bind_service=+ep' `which armadietto` ```\n\n* Ideally, run your storage inside a container or on a dedicated machine\n\nIf you're using the Redis backend, apply similar access restrictions to the\ndatabase and to any files containing the database access credentials.\n\n## Serving over HTTPS\n\nSince RemoteStorage is a system for storing arbitrary user-specific data, and\nsince it makes use of OAuth 2.0, we strongly recommend you serve it over a secure\nconnection. You can boot the server to listen for HTTP or HTTPS requests or\nboth.  \nIf armadietto is behind a reverse proxy on the same machine, the proxy can handle TLS, \nso armadietto only needs to set `enable` and `force` in the https configuration.\nThe reverse proxy must set the header `x-forwarded-proto` (or `x-forwarded-ssl` or `x-forwarded-scheme`) in the request passed to Armadietto. Armadietto does not yet support the `Forwarded` header.\n\nThis configuration (for the monolithic server) boots the app on two ports, one secure and one\nplaintext:\n\n```js\nconst server = new Armadietto({\n  store: store,\n  http: {\n    host: '127.0.0.1',\n    port: 8000\n  },\n  https: {\n    force: true,\n    host:  '127.0.0.1',\n    port:  4343,\n    key:   'path/to/ssl.key',\n    cert:  'path/to/ssl.crt',\n    ca:    'path/to/ca.pem'    // optional\n  },\n  logging: {\n    stdout: [\"debug\"],\n    log_files: [\"error\"],\n    log_dir: \"./some-log-dir\"\n  }\n\n});\n\nserver.boot();\n```\n\nFor example, if you use certificates from [Lets Encrypt](https://letsencrypt.org), you will set\n```\n    cert: \"/etc/letsencrypt/live/domainname/cert.pem\",\n    key: \"/etc/letsencrypt/live/domainname/privkey.pem\"\n```\nwhere domainname is (usually) the DNS name of your server.\n\nThe `force: true` line in the `https` section means the app will:\n\n* Return HTTPS URLs in WebFinger responses\n* Force sign-up and OAuth login pages onto an HTTPS connection\n* Refuse to process POST authentication requests over insecure connections\n* Block insecure storage requests and revoke the client's access\n\nArmadietto considers a request to be secure if:\n\n* armadietto itself acts as an SSL terminator and the connection to it is encrypted\n* The `X-Forwarded-SSL` header has the value `on`\n* The `X-Forwarded-Proto` header has the value `https`\n* The `X-Forwarded-Scheme` header has the value `https`\n\nSo you can have an SSL-terminating proxy in front of armadietto as long as it sets\none of those headers, and *does not* let external clients set them. In this\nsetup, you can set `https.force = true` but omit `https.port`; this means\narmadietto itself will not accept encrypted connections but will apply the above\nbehaviour to enforce secure connections.\n\n\n## Debugging an installation\n\nSet the environment `DEBUG` to enable logging.  For example `DEBUG=true armadietto -c /etc/armadietto/conf.json`\n\n## Development\n\nSee `DEVELOPMENT.md`\n\n## License\n\n(The MIT License)\n\nCopyright © 2012–2015 James Coglan\nCopyright © 2018–2025 remoteStorage contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the 'Software'), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\nthe Software, and to permit persons to whom the Software is furnished to do so,\nsubject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\nFOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\nCOPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\nCONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fremotestorage%2Farmadietto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fremotestorage%2Farmadietto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fremotestorage%2Farmadietto/lists"}