# Magic Wormhole Mailbox Server
[](https://pypi.python.org/pypi/magic-wormhole-mailbox-server)
[](https://codecov.io/github/magic-wormhole/magic-wormhole-transit-relay?branch=master)
This repository holds the code for the main server that
[Magic-Wormhole](http://magic-wormhole.io) clients connect to. The server
performs store-and-forward delivery for small key-exchange and control
messages. Bulk data is sent over a direct TCP connection, or through a
[transit-relay](https://github.com/magic-wormhole/magic-wormhole-transit-relay).
Clients connect with WebSockets, for low-latency delivery in the happy case
where both clients are attached at the same time. Message are stored to
enable non-simultaneous clients to make forward progress. The server uses a
small SQLite database for persistence (and clients will reconnect
automatically, allowing the server to be rebooted without losing state). An
optional "usage DB" tracks historical activity for status monitoring and
operational maintenance.
## Installation
```
pip install magic-wormhole-mailbox-server
```
You either want to do this into a "user" environment (putting the ``twist``
and ``twistd`` executables in ``~/.local/bin/``) like this:
```
pip install --user magic-wormhole-mailbox-server
```
or put it into a virtualenv, to avoid modifying the system python's
libraries, like this:
```
virtualenv venv
source venv/bin/activate
pip install magic-wormhole-mailbox-server
```
You probably *don't* want to use ``sudo`` when you run ``pip``, since the
dependencies that get installed may conflict with other python programs on
your computer. ``pipsi`` is usually a good way to install into isolated
environments, but unfortunately it doesn't work for
magic-wormhole-mailbox-server, because we don't have a dedicated command to
start the server (``twist``, described below, comes from the ``twisted``
package, and pipsi doesn't expose executables from dependencies).
For the installation from source, ``clone`` this repo, ``cd`` into the folder,
create and activate a virtualenv, and run ``pip install .``.
## Running A Server
Note that the standard [Magic-Wormhole](http://magic-wormhole.io)
command-line tool is preconfigured to use a mailbox server hosted by the
project, so running your own server is only necessary for custom applications
that use magic-wormhole as a library.
The mailbox server is deployed as a twist/twistd plugin. Running a basic
server looks like this:
```
twist wormhole-mailbox --usage-db=usage.sqlite
```
Use ``twist wormhole-mailbox --help`` for more details.
If you use the default ``--port=tcp:4000``, on a machine named
``example.com``, then clients can reach your server with the following
option:
```
wormhole --relay-url=ws://example.com:4000/v1 send FILENAME
```
## Using Docker
Dockerfile content:
```dockerfile
FROM python:3.8
RUN pip install magic-wormhole-mailbox-server
CMD [ "twist", "wormhole-mailbox","--usage-db=usage.sqlite" ]
```
> Note: This will be running as root, you should adjust it to be in user space for production.
Build and run:
```shell
docker build -t magicwormhole Dockerfile
docker run -p 4000:4000 -d magicwormhole
```
Connect:
```shell
wormhole --relay-url=ws://localhost:4000/v1 send FILENAME
```
## License, Compatibility
This library is released under the MIT license, see LICENSE for details.
This library is compatible with python2.7, and python3 (3.5 and higher).
Raw data
{
"_id": null,
"home_page": "https://github.com/warner/magic-wormhole-mailbox-server",
"name": "magic-wormhole-mailbox-server",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Brian Warner",
"author_email": "warner-magic-wormhole@lothar.com",
"download_url": "https://files.pythonhosted.org/packages/9d/5c/71566147af3f28017035ebe69ce7253ea26917225ae7c39b964578541bff/magic-wormhole-mailbox-server-0.5.1.tar.gz",
"platform": null,
"description": "# Magic Wormhole Mailbox Server\n[](https://pypi.python.org/pypi/magic-wormhole-mailbox-server)\n\n[](https://codecov.io/github/magic-wormhole/magic-wormhole-transit-relay?branch=master)\n\nThis repository holds the code for the main server that\n[Magic-Wormhole](http://magic-wormhole.io) clients connect to. The server\nperforms store-and-forward delivery for small key-exchange and control\nmessages. Bulk data is sent over a direct TCP connection, or through a\n[transit-relay](https://github.com/magic-wormhole/magic-wormhole-transit-relay).\n\nClients connect with WebSockets, for low-latency delivery in the happy case\nwhere both clients are attached at the same time. Message are stored to\nenable non-simultaneous clients to make forward progress. The server uses a\nsmall SQLite database for persistence (and clients will reconnect\nautomatically, allowing the server to be rebooted without losing state). An\noptional \"usage DB\" tracks historical activity for status monitoring and\noperational maintenance.\n\n## Installation\n\n```\npip install magic-wormhole-mailbox-server\n```\n\nYou either want to do this into a \"user\" environment (putting the ``twist``\nand ``twistd`` executables in ``~/.local/bin/``) like this:\n\n```\npip install --user magic-wormhole-mailbox-server\n```\n\nor put it into a virtualenv, to avoid modifying the system python's\nlibraries, like this:\n\n```\nvirtualenv venv\nsource venv/bin/activate\npip install magic-wormhole-mailbox-server\n```\n\nYou probably *don't* want to use ``sudo`` when you run ``pip``, since the\ndependencies that get installed may conflict with other python programs on\nyour computer. ``pipsi`` is usually a good way to install into isolated\nenvironments, but unfortunately it doesn't work for\nmagic-wormhole-mailbox-server, because we don't have a dedicated command to\nstart the server (``twist``, described below, comes from the ``twisted``\npackage, and pipsi doesn't expose executables from dependencies).\n\nFor the installation from source, ``clone`` this repo, ``cd`` into the folder,\ncreate and activate a virtualenv, and run ``pip install .``.\n\n## Running A Server\n\nNote that the standard [Magic-Wormhole](http://magic-wormhole.io)\ncommand-line tool is preconfigured to use a mailbox server hosted by the\nproject, so running your own server is only necessary for custom applications\nthat use magic-wormhole as a library.\n\nThe mailbox server is deployed as a twist/twistd plugin. Running a basic\nserver looks like this:\n\n```\ntwist wormhole-mailbox --usage-db=usage.sqlite\n```\n\nUse ``twist wormhole-mailbox --help`` for more details.\n\nIf you use the default ``--port=tcp:4000``, on a machine named\n``example.com``, then clients can reach your server with the following\noption:\n\n```\nwormhole --relay-url=ws://example.com:4000/v1 send FILENAME\n```\n\n## Using Docker\n\nDockerfile content:\n```dockerfile\nFROM python:3.8\nRUN pip install magic-wormhole-mailbox-server\nCMD [ \"twist\", \"wormhole-mailbox\",\"--usage-db=usage.sqlite\" ] \n```\n> Note: This will be running as root, you should adjust it to be in user space for production.\n\nBuild and run:\n```shell\ndocker build -t magicwormhole Dockerfile\ndocker run -p 4000:4000 -d magicwormhole\n```\n\nConnect:\n```shell\nwormhole --relay-url=ws://localhost:4000/v1 send FILENAME\n```\n\n## License, Compatibility\n\nThis library is released under the MIT license, see LICENSE for details.\n\nThis library is compatible with python2.7, and python3 (3.5 and higher).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Securely transfer data between computers",
"version": "0.5.1",
"project_urls": {
"Homepage": "https://github.com/warner/magic-wormhole-mailbox-server"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a3ec096238f31f8cc198f8a8f953b6c57aea738764e47ce5c41438e8a4f978f6",
"md5": "9c82c6087c242bc060e2f13201376a5e",
"sha256": "7ec83164aa5269883c66522950dbf5e26214695b447f60b1ee0acacc31f8eb74"
},
"downloads": -1,
"filename": "magic_wormhole_mailbox_server-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9c82c6087c242bc060e2f13201376a5e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 46177,
"upload_time": "2024-11-10T02:28:21",
"upload_time_iso_8601": "2024-11-10T02:28:21.829003Z",
"url": "https://files.pythonhosted.org/packages/a3/ec/096238f31f8cc198f8a8f953b6c57aea738764e47ce5c41438e8a4f978f6/magic_wormhole_mailbox_server-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9d5c71566147af3f28017035ebe69ce7253ea26917225ae7c39b964578541bff",
"md5": "bb9f84e7ecddc43413b4287b7b20d285",
"sha256": "a007a03672293204657681dbf502045d6d5817c57f9aae2f2226e6ea1a008ca1"
},
"downloads": -1,
"filename": "magic-wormhole-mailbox-server-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "bb9f84e7ecddc43413b4287b7b20d285",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 69758,
"upload_time": "2024-11-10T02:28:23",
"upload_time_iso_8601": "2024-11-10T02:28:23.646823Z",
"url": "https://files.pythonhosted.org/packages/9d/5c/71566147af3f28017035ebe69ce7253ea26917225ae7c39b964578541bff/magic-wormhole-mailbox-server-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-10 02:28:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "warner",
"github_project": "magic-wormhole-mailbox-server",
"travis_ci": true,
"coveralls": true,
"github_actions": true,
"appveyor": true,
"tox": true,
"lcname": "magic-wormhole-mailbox-server"
}
JSON
