Organize docs. (#80)
This commit is contained in:
Antonio Navarro Perez
GitHub
parent
891afabb6d
commit
0a96f836b7
7 changed files with 145 additions and 110 deletions
37
README.md
37
README.md
|
|
@ -29,38 +29,37 @@
|
|||
|
||||
![Distribyted Screen Shot][product-screenshot]
|
||||
|
||||
Distribyted tries to make easier integrations with other applications among torrent files, presenting them as a standard filesystem.
|
||||
Distribyted is an alternative torrent client.
|
||||
It can expose torrent files as a standard FUSE mount or webDAV endpoint and download them on demand, allowing random reads using a fixed amount of disk space.
|
||||
|
||||
We aim to use some compressed file characteristics to avoid download it entirely, just the parts that we'll need.
|
||||
|
||||
Also, if the file format is not supported, distribyted can stream and seek through the file if needed.
|
||||
Distribyted tries to make easier integrations with other applications using torrent files, presenting them as a standard filesystem.
|
||||
|
||||
**Note that distribyted is in alpha version, it is a proof of concept with a lot of bugs.**
|
||||
|
||||
### Use Cases
|
||||
## Use Cases
|
||||
|
||||
- Play **multimedia files** on your favorite video or audio player. These files will be downloaded on demand and only the needed parts.
|
||||
- Explore TBs of data from public **datasets** only downloading the parts you need. Use **Jupyter Notebooks** directly to process or analyze this data.
|
||||
- Play your **ROM backups** directly from the torrent file. You can have virtually GBs in games and only downloaded the needed ones.
|
||||
|
||||
### Supported _Expandable_ File Formats
|
||||
Distribyted can show some kind of files directly as folders, making it possible for applications read only the parts that they need. Here is a list of supported, to be supported and not supported formats.
|
||||
|
||||
#### Supported
|
||||
- zip: Able to uncompress just one file. The file is decompressed to a temporal file sequentially to make possible seek over it. The decompression stops if no one is reading it.
|
||||
|
||||
#### To Be Supported
|
||||
- tar: Seek to any file and inside that files using a [modified standard library](https://github.com/ajnavarro/go-tar). Not useful on `.tar.gz` files.
|
||||
- 7zip: Similar to Zip. Need for a library similar to [zip](https://github.com/saracen/go7z).
|
||||
- xz: Only worth it when the file is created using blocks. Possible library [here](https://github.com/ulikunitz/xz) and [here](https://github.com/frrad/bxzf).
|
||||
|
||||
#### Not Supported
|
||||
- gzip: As far as I know, it doesn't support random access.
|
||||
|
||||
## Documentation
|
||||
|
||||
Check [here][main-url] or [here][doc-folder-url] for further documentation.
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
|
||||
|
||||
1. Fork the Project
|
||||
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
|
||||
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. Push to the Branch (`git push origin feature/AmazingFeature`)
|
||||
5. Open a Pull Request
|
||||
|
||||
## License
|
||||
|
||||
Distributed under the GPL3 license. See `LICENSE` for more information.
|
||||
|
||||
[doc-folder-url]: https://github.com/distribyted/distribyted/blob/master/mkdocs/docs/index.md
|
||||
[main-url]: https://distribyted.com
|
||||
[releases-shield]: https://img.shields.io/github/v/release/distribyted/distribyted.svg?style=flat-square
|
||||
|
|
|
|||
1
mkdocs/docs/api-reference.md
Normal file
1
mkdocs/docs/api-reference.md
Normal file
|
|
@ -0,0 +1 @@
|
|||
TBD
|
||||
1
mkdocs/docs/architecture.md
Normal file
1
mkdocs/docs/architecture.md
Normal file
|
|
@ -0,0 +1 @@
|
|||
TBD
|
||||
76
mkdocs/docs/getting-started.md
Normal file
76
mkdocs/docs/getting-started.md
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
## Installation
|
||||
|
||||
### Using the binary
|
||||
|
||||
Get the latest release from [releases][releases-url] page or download the source code and execute `make build`.
|
||||
|
||||
Run the program: `./distribyted-[VERSION]-[OS]-[ARCH]`
|
||||
|
||||
Defaults are good enough for starters, but you can change them. Here is the output of `./distribyted -help`:
|
||||
|
||||
```text
|
||||
NAME:
|
||||
distribyted - Torrent client with on-demand file downloading as a filesystem.
|
||||
|
||||
USAGE:
|
||||
distribyted [global options] [arguments...]
|
||||
|
||||
GLOBAL OPTIONS:
|
||||
--config value YAML file containing distribyted configuration. (default: "./distribyted-data/config.yaml") [$DISTRIBYTED_CONFIG]
|
||||
--http-port value HTTP port for web interface (default: 4444) [$DISTRIBYTED_HTTP_PORT]
|
||||
--fuse-allow-other Allow other users to acces to all fuse mountpoints. You need to add user_allow_other flag to /etc/fuse.conf file. (default: false) [$DISTRIBYTED_FUSE_ALLOW_OTHER]
|
||||
--help, -h show help (default: false)
|
||||
```
|
||||
|
||||
#### Prerequisites on windows
|
||||
|
||||
Download and install [WinFsp](http://www.secfs.net/winfsp/).
|
||||
|
||||
### Using Docker
|
||||
|
||||
Docker run example:
|
||||
|
||||
```shell
|
||||
docker run \
|
||||
--rm -p 4444:4444 -p 36911:36911 \
|
||||
--cap-add SYS_ADMIN \
|
||||
--device /dev/fuse \
|
||||
--security-opt apparmor:unconfined \
|
||||
-v /tmp/mount:/distribyted-data/mount:shared \
|
||||
-v /tmp/metadata:/distribyted-data/metadata \
|
||||
-v /tmp/config:/distribyted-data/config \
|
||||
distribyted/distribyted:latest
|
||||
```
|
||||
|
||||
Docker compose example:
|
||||
|
||||
```yaml
|
||||
distribyted:
|
||||
container_name: distribyted
|
||||
image: distribyted/distribyted:latest
|
||||
restart: always
|
||||
ports:
|
||||
- "4444:4444/tcp"
|
||||
- "36911:36911/tcp"
|
||||
volumes:
|
||||
- /home/user/mount:/distribyted-data/mount:shared
|
||||
- /home/user/metadata:/distribyted-data/metadata
|
||||
- /home/user/config:/distribyted-data/config
|
||||
security_opt:
|
||||
- apparmor:unconfined
|
||||
devices:
|
||||
- /dev/fuse
|
||||
cap_add:
|
||||
- SYS_ADMIN
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
After executing and load all torrent or magnet files, a web interface will be available at `http://localhost:4444`
|
||||
It contains information about the mounted routes and torrent files like download/upload speed, leechers, seeders...
|
||||
|
||||
You can also modify the configuration file and reload the server from `http://localhost:4444/config` .
|
||||
|
||||
### Configuration File
|
||||
|
||||
You can see the default configuration file with some explanation comments [here](https://github.com/distribyted/distribyted/blob/master/templates/config_template.yaml).
|
||||
|
|
@ -1,93 +1,36 @@
|
|||
# Main
|
||||
|
||||
## Getting Started
|
||||
|
||||
Get the latest release from [releases][releases-url] page or download the source code and execute `make build`.
|
||||
|
||||
Run the program: `./distribyted-[VERSION]-[OS]-[ARCH]`
|
||||
|
||||
Defaults are good enough for starters, but you can change them. Here is the output of `./distribyted -help`:
|
||||
|
||||
```text
|
||||
NAME:
|
||||
distribyted - Torrent client with on-demand file downloading as a filesystem.
|
||||
|
||||
USAGE:
|
||||
distribyted [global options] [arguments...]
|
||||
|
||||
GLOBAL OPTIONS:
|
||||
--config value YAML file containing distribyted configuration. (default: "./distribyted-data/config.yaml") [$DISTRIBYTED_CONFIG]
|
||||
--http-port value HTTP port for web interface (default: 4444) [$DISTRIBYTED_HTTP_PORT]
|
||||
--fuse-allow-other Allow other users to acces to all fuse mountpoints. You need to add user_allow_other flag to /etc/fuse.conf file. (default: false) [$DISTRIBYTED_FUSE_ALLOW_OTHER]
|
||||
--help, -h show help (default: false)
|
||||
```
|
||||
|
||||
### Prerequisites on windows
|
||||
|
||||
Download and install [WinFsp](http://www.secfs.net/winfsp/).
|
||||
|
||||
## Usage
|
||||
|
||||
After executing and load all torrent or magnet files, a web interface will be available here: `http://localhost:4444`
|
||||
It contains information about the mounted routes and torrent files like download/upload speed, leechers, seeders...
|
||||
|
||||
You can also modify the configuration file and reload the server from here: `http://localhost:4444/config` .
|
||||
|
||||
### Docker
|
||||
|
||||
Docker run example:
|
||||
|
||||
```shell
|
||||
docker run \
|
||||
--rm -p 4444:4444 -p 36911:36911 \
|
||||
--cap-add SYS_ADMIN \
|
||||
--device /dev/fuse \
|
||||
--security-opt apparmor:unconfined \
|
||||
-v /tmp/mount:/distribyted-data/mount:shared \
|
||||
-v /tmp/metadata:/distribyted-data/metadata \
|
||||
-v /tmp/config:/distribyted-data/config \
|
||||
distribyted/distribyted:latest
|
||||
```
|
||||
|
||||
Docker compose example:
|
||||
|
||||
```yaml
|
||||
distribyted:
|
||||
container_name: distribyted
|
||||
image: distribyted/distribyted:latest
|
||||
restart: always
|
||||
ports:
|
||||
- "4444:4444/tcp"
|
||||
- "36911:36911/tcp"
|
||||
volumes:
|
||||
- /home/user/mount:/distribyted-data/mount:shared
|
||||
- /home/user/metadata:/distribyted-data/metadata
|
||||
- /home/user/config:/distribyted-data/config
|
||||
security_opt:
|
||||
- apparmor:unconfined
|
||||
devices:
|
||||
- /dev/fuse
|
||||
cap_add:
|
||||
- SYS_ADMIN
|
||||
```
|
||||
|
||||
### Configuration File
|
||||
|
||||
You can see the default configuration file with some explanation comments [here](https://github.com/distribyted/distribyted/blob/master/templates/config_template.yaml).
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
|
||||
|
||||
1. Fork the Project
|
||||
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
|
||||
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. Push to the Branch (`git push origin feature/AmazingFeature`)
|
||||
5. Open a Pull Request
|
||||
|
||||
## License
|
||||
|
||||
Distributed under the GPL3 license. See `LICENSE` for more information.
|
||||
Distribyted is an alternative torrent client.
|
||||
It can expose torrent files as a standard FUSE mount or webDAV endpoint and download them on demand, allowing random reads using a fixed amount of disk space.
|
||||
|
||||
![Distribyted Screen Shot][product-screenshot]
|
||||
|
||||
[product-screenshot]: images/distribyted.gif
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
### User Interfaces
|
||||
|
||||
Distribyted supports several ways to expose the files to the user or external applications:
|
||||
|
||||
#### Supported
|
||||
|
||||
- FUSE: Other applications can access to torrent files directly as a filesystem.
|
||||
- WebDAV: Applications that supports WebDAV can access torrent files using this protocol. It is recommended when distribyted is running in a remote machine or using docker.
|
||||
|
||||
#### To be supported
|
||||
- HTTP: distribyted will support direct HTTP access to files.
|
||||
|
||||
### _Expandable_ File Formats
|
||||
Distribyted can show some kind of files directly as folders, making it possible for applications read only the parts that they need. Here is a list of supported, to be supported and not supported formats.
|
||||
|
||||
#### Supported
|
||||
- zip: Able to uncompress just one file. The file is decompressed to a temporal file sequentially to make possible seek over it. The decompression stops if no one is reading it.
|
||||
|
||||
#### To Be Supported
|
||||
- tar: Seek to any file and inside that files using a [modified standard library](https://github.com/ajnavarro/go-tar). Not useful on `.tar.gz` files.
|
||||
- 7zip: Similar to Zip. Need for a library similar to [zip](https://github.com/saracen/go7z).
|
||||
- xz: Only worth it when the file is created using blocks. Possible library [here](https://github.com/ulikunitz/xz) and [here](https://github.com/frrad/bxzf).
|
||||
|
||||
#### Not Supported
|
||||
- gzip: As far as I know, it doesn't support random access.
|
||||
|
|
|
|||
1
mkdocs/docs/tutorials.md
Normal file
1
mkdocs/docs/tutorials.md
Normal file
|
|
@ -0,0 +1 @@
|
|||
TBD
|
||||
|
|
@ -1,18 +1,28 @@
|
|||
site_name: Distribyted Documentation
|
||||
site_name: Distribyted
|
||||
site_url: https://distribyted.com/
|
||||
repo_url: https://github.com/distribyted/distribyted
|
||||
repo_name: distribyted/distribyted
|
||||
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Getting Started: getting-started.md
|
||||
- Tutorials: tutorials.md
|
||||
- API Reference: api-reference.md
|
||||
|
||||
theme:
|
||||
logo: images/distribyted_icon.png
|
||||
icon:
|
||||
repo: fontawesome/brands/github
|
||||
name: material
|
||||
palette:
|
||||
primary: blue
|
||||
primary: white
|
||||
features:
|
||||
- navigation.tabs
|
||||
- navigation.instant
|
||||
- navigation.tracking
|
||||
- navigation.expand
|
||||
- navigation.indexes
|
||||
- navigation.top
|
||||
- toc.integrate
|
||||
|
||||
edit_uri: edit/master/mkdocs/docs/
|
||||
|
|
@ -24,3 +34,7 @@ extra:
|
|||
version:
|
||||
default: latest
|
||||
provider: mike
|
||||
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink: true
|
||||
|
|
|
|||
Loading…
Reference in a new issue