{"id":22064359,"url":"https://github.com/orbitdb/voyager","last_synced_at":"2025-04-07T07:01:30.453Z","repository":{"id":40746696,"uuid":"189651744","full_name":"orbitdb/voyager","owner":"orbitdb","description":"Storage service for OrbitDB peer-to-peer databases","archived":false,"fork":false,"pushed_at":"2025-03-20T15:50:36.000Z","size":1009,"stargazers_count":40,"open_issues_count":8,"forks_count":16,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-31T06:03:28.560Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/orbitdb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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-05-31T20:02:06.000Z","updated_at":"2025-03-20T15:50:42.000Z","dependencies_parsed_at":"2023-02-05T02:00:35.537Z","dependency_job_id":"0a9b8244-8972-4628-af9f-9641ae280f3c","html_url":"https://github.com/orbitdb/voyager","commit_stats":null,"previous_names":["orbitdb/voyager","orbitdb/orbit-db-pinner"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orbitdb%2Fvoyager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orbitdb%2Fvoyager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orbitdb%2Fvoyager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orbitdb%2Fvoyager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orbitdb","download_url":"https://codeload.github.com/orbitdb/voyager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608150,"owners_count":20965952,"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":[],"created_at":"2024-11-30T19:09:00.555Z","updated_at":"2025-04-07T07:01:30.408Z","avatar_url":"https://github.com/orbitdb.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Voyager\n\n[![Matrix](https://img.shields.io/matrix/orbit-db%3Amatrix.org)](https://app.element.io/#/room/#orbit-db:matrix.org) [![npm (scoped)](https://img.shields.io/npm/v/%40orbitdb/voyager)](https://www.npmjs.com/package/@orbitdb/voyager) [![node-current (scoped)](https://img.shields.io/node/v/%40orbitdb/voyager)](https://www.npmjs.com/package/@orbitdb/voyager)\n\nA **storage service** for [OrbitDB](https://github.com/orbitdb/orbitdb) peer-to-peer databases.\n\nVoyager replicates and stores OrbitDB databases and makes them available to others when the database's originating peer is offline.\n\nIt is designed to run on systems with guaranteed uptime and public availability and can be seen as a \"data availability node\" for OrbitDB. For example, a browser-based app running a OrbitDB database may rely on one or more Voyager peers to ensure the database is available when the browser peer is unreachable.\n\n***Note!*** *This software is currently in alpha version status and thus may change, break backwards compatibility or contain major issues. It has not been security audited. Use it accordingly.*\n\n## Installation\n\nTo use Voyager as a module:\n\n```sh\nnpm i @orbitdb/voyager\n```\n\nTo use Voyager from the CLI:\n\n```sh\nnpm i -g @orbitdb/voyager\n```\n\n## Usage\n\n### CLI\n\nThe `voyager` CLI tool can be used to manage a Voyager instance. Run `voyager` on the command line to get started.\n\nCurrently the following commands are available:\n\n```\nvoyager daemon   Launch Voyager\nvoyager id       Show the voyager's id\nvoyager address  Show the voyager's network addresses\nvoyager auth     Add or remove authorized user\n```\n\n### Daemon\n\nVoyager can be run as a daemon process. You can install the package globally and run it using the `voyager` CLI binary:\n\n```sh\nvoyager daemon\n```\n\nTo store Voyager's configuration and data to a different directory, use the `-d` or `--directory` flag or `VOYAGER_PATH` environment variable:\n\n```sh\nvoyager daemon -d /path/to/voyager\n```\n\n```sh\nVOYAGER_PATH=/path/to/voyager voyager daemon\n```\n\n#### Command Line Options\n\nVoyager daemon supports several command line options:\n\n**Help**\n- `--help, -h`: Shows command line help\n\n**Port Configuration**\n- `--port, -p`: The port to listen on for the libp2p TCP transport. Defaults to 0 (random available port).\n- `--wsport, -w`: The port to listen on for WebSockets. Defaults to 0 (random available port).\n\n**Logging**\n- `--verbose, -v`: Enable verbose logging. Use multiple times (e.g., `-vvv`) for increased verbosity.\n\n**Access Control**\n- `--allow, -a`: Allow anyone to add a database. The default is false (deny all except explicitly authorized users).\n\n**Storage Location**\n- `--directory, -d`: Specify a directory to store Voyager, IPFS, and OrbitDB data. You can also use the `VOYAGER_PATH` environment variable.\n\n**Example with multiple options:**\n```sh\nvoyager daemon -p 9090 -w 9091 -vvv --allow\n```\n\n\n\n### Docker\n\nYou can run an Voyager storage service using a pre-configured Docker image.\n\nOnce you have cloned this repo, cd into the voyager directory root and run:\n\n```\ndocker build -t orbitdb-voyager ./\ndocker run --rm -d -p 8000:8000 orbitdb-voyager\n```\n\nAdjust the port if required.\n\n## Managing Voyager Access\n\nVoyager will deny all requests by default. To allow a user to interact with Voyager, the (requesting) user's `id` must be added to Voyager's \"allow\" list.\n\nAccess can be configured in two ways; from the terminal and programmatically, using RPC.\n\n**NOTE** The user's `id` used in the examples below can be retrieved using **`orbitdb.identity.id`**, which is available from the user's OrbitDB instance.\n\n### Managing access from the terminal\n\nTo add an authorized user to Voyager:\n\n```sh\nvoyager auth add \u003cid\u003e\n```\n\nwhere `\u003cid\u003e` identifies a user who can add databases to this Voyager instance. The `\u003cid\u003e` is the string from user's OrbitDB instance `orbitdb.identity.id`.\n\nTo remove an authorized user from Voyager:\n\n```sh\nvoyager auth del \u003cid\u003e\n```\n\nwhere `\u003cid\u003e` identifies a user who can add databases to this Voyager instance. The `\u003cid\u003e` is the string from user's OrbitDB instance `orbitdb.identity.id`.\n\nList authorized users:\n\n```sh\nvoyager auth list\n```\n\nIf Voyager is deployed to a custom directory, call Voyager with the `-d` or `--directory` flag, or `VOYAGER_PATH`environment variable, and specify the directory:\n\n```sh\nvoyager auth add -d /custom/voyager/path \u003cid\u003e\nvoyager auth remove -d /custom/voyager/path \u003cid\u003e\nvoyager auth list -d /custom/voyager/path\n```\n\n```sh\nVOYAGER_PATH=/custom/voyager/path voyager auth add \u003cid\u003e\nVOYAGER_PATH=/custom/voyager/path voyager auth remove \u003cid\u003e\nVOYAGER_PATH=/custom/voyager/path voyager auth list\n```\n\n### Managing access using RPC\n\nAuthorizing users can be carried out programmatically using Voyager's RPC function.\n\nStart by instantiating the rpc:\n\n```\nimport { RPC } from '@orbitdb/voyager'\n\nconst rpc = await RPC({ directory: '' })\n```\n\nTo add an authorization:\n\n```\nconst id = '037ba2545db2e2ec0ba17fc9b35fbbf6bc09db82c9ab324521e62693e8aa96ceb4'\nawait rpc.authAdd({ id })\n```\n\nTo list all authorizations:\n\n```\nconst { message } = await rpc.authList()\nconsole.log(message)\n```\n\nAnd to remove an authorization:\n\n```\nawait rpc.authDel()\n```\n\n## Adding databases to Voyager\n\nTo make databases accessible from a Voyager storage service, the database needs to be added to a Voyager instance. This can be achieved programmatically by using the **Voyager remote API** module.\n\nTo use Voyager remote API, first install the [@orbitdb/voyager](https://www.npmjs.com/package/@orbitdb/voyager) package:\n\n```sh\nnpm i @orbitdb/voyager\n```\n\nNext, instantiate Voyager remote API:\n\n```js\nimport { createLibp2p } from 'libp2p'\nimport { createHelia } from 'helia'\nimport { createOrbitDB } from '@orbitdb/core'\nimport { Voyager } from '@orbitdb/voyager'\n\n// set up libp2p, helia and orbitdb\nconst libp2p = await createLibp2p()\nconst ipfs = await createHelia({ libp2p })\nconst orbitdb = await createOrbitDB({ ipfs })\n\n// deployed voyager peer's listening address, it looks like this:\n// /ip4/127.0.0.1/tcp/54322/p2p/16Uiu2HAmATMovCwY46yyJib7bGZF2f2XLRar7d7R3NJCSJtuyQLt\nconst address = '...'\n\nconst voyager = await Voyager({ orbitdb, address })\n``` \n\nTo add a database to voyager:\n\n```js\n// create a db to be added to voyager\nconst db = await orbitdb.open('my-db')\n\n// add the address to voyager (can also pass an array of addresses)\nawait voyager.add(db.address)\n```\n\nTo remove a database from voyager:\n\n```js\n// open an instance of the db you want to remove from voyager\nconst db = await orbitdb.open('my-db')\n\n// remove the address from voyager (can also pass an array of addresses)\nawait voyager.remove(db.address)\n```\n\n## The OrbitDB Voyager Protocol\n\nVoyager uses Libp2p to add and remove databases to replicate to and from the storage service. A database can be added or removed by dialling the protocol and issuing a request message.\n\n### Protocol\n\nThe protocol identifier is:\n\n```\n/orbitdb/voyager/v1.0.0\n```\n\n### Messages\n\nSend one of the following messages to the protocol in order to communicate with the service:\n\n#### Adding a DB for replication\n\n```\ntype: 1 (\"ADD\")\nid: The id of the requester\nsignature: One or more database addresses signed by the requester\naddresses: One or more database addresses to add to the storage \n```\n\nIf successful, an OK response will be sent. If it fails, an error will be returned.\n\n#### Removing a DB for replication\n\n```\ntype: 2 (\"REMOVE\")\nid: The id of the requester\nsignature: One or more database addresses signed by the requester\naddresses: One or more database addresses to remove from the storage\n```\n\nIf successful, an OK response will be sent. If it fails, an error will be returned.\n\n## Allowing and Denying User Access\n\nVoyager uses simple ALLOW/DENY policies to authorize the messages received through the protocol.\n\nVoyager can either be run in ALLOW ALL mode where anyone can send a message except those who appear in the denied list or DENY ALL mode which will only allow messages from an explicit list of users. The default access mode is DENY ALL.\n\n## License\n\n[MIT](LICENSE) © 2024 OrbitDB Community\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forbitdb%2Fvoyager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forbitdb%2Fvoyager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forbitdb%2Fvoyager/lists"}