Skip to content

Commit a675ad8

Browse files
committed
Merge #394: Review docs
7383916 docs: [#379] review Development Guide (Jose Celano) 21b533e docs: [#379] review Containerization Guide (Jose Celano) 28da3bd docs: [#379] review User Guide (Jose Celano) 585fbe7 docs: [#379] reorganize docs sections (Jose Celano) 81422fd docs: [#379] update README (Jose Celano) Pull request description: - [x] Update README - [x] Reorganize docs in 4 guides - [x] Review User Guide - [x] Review Development Guide - [x] Review Containerization Guide - [x] Review Release Process Guide ACKs for top commit: josecelano: ACK 7383916 Tree-SHA512: 3e1a89e2670c2dd5af4ab78d2bd2c97104c2a2c9520b13843b982d8ceb82875fa954b0e3ccdabab773194d26dd6ae83de56dbcbf9a3505ac4a9d6e1f9484c047
2 parents 131472a + 7383916 commit a675ad8

File tree

6 files changed

+485
-364
lines changed

6 files changed

+485
-364
lines changed

README.md

Lines changed: 117 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -13,53 +13,147 @@ This web GUI connects using the [Torrust Index Application Interface](https://gi
1313
## Key Features
1414

1515
* [X] Built with [Nuxt](https://nuxt.com/) and [Vue 3](https://vuejs.org/).
16-
* [X] Modern design
17-
* [X] Categories and tags
18-
* [X] Search
19-
* [X] Sorting
20-
* [X] Filtering
21-
* [X] Pagination
16+
* [X] Modern design.
17+
* [X] Categories and tags.
18+
* [X] Search.
19+
* [X] Sorting.
20+
* [X] Filtering.
21+
* [X] Pagination.
2222
* [X] Admin settings: tracker, categories, tags, etc.
23+
* [X] Support for BitTorrent v1.
24+
25+
> NOTE: It does not support the [BitTorrent Protocol Specification v2][BEP_52].
2326
2427
You can see some [screenshots](./docs/screenshots.md) of the application.
2528

2629
## Getting Started
2730

28-
Requirements:
31+
### Container Version
32+
33+
The Torrust Index GUI is [deployed to DockerHub][dockerhub], you can run a demo immediately with the following commands:
34+
35+
#### Docker
36+
37+
```sh
38+
docker run -it --publish="3000:3000/tcp" torrust/index-gui:develop
39+
```
40+
41+
> Please read our [container guide][containers] for more information.
42+
43+
#### Podman
44+
45+
```sh
46+
podman run -it --publish="3000:3000/tcp" docker.io/torrust/index-gui:develop
47+
```
48+
49+
> Please read our [container guide][containers] for more information.
50+
51+
### Development Version
52+
53+
#### Requirements
54+
55+
* Node >= `20.10.0`
56+
57+
You can follow the [documentation](./docs/index.md) to install and use Torrust Index GUI for development.
58+
59+
There are some missing sections in the documentation like an installation guide for production. Contributions to the documentation are welcome.
60+
61+
#### Checkout and Run
62+
63+
```sh
64+
# Checkout repository into a new folder:
65+
git clone https://github.com/torrust/torrust-index-gui.git && cd torrust-index-gui
66+
67+
# Install dependencies
68+
npm install
69+
70+
# Run development server
71+
npm run dev
72+
```
2973

30-
* Node >= 19.0.0
74+
#### Customization
3175

32-
You can follow the [documentation](./docs/index.md) to install and use Torrust Index Frontend for development. We will improve the documentation with:
76+
You can use environment variables to customize the application infrastructure settings.
3377

34-
* Installation guide for production.
35-
* Docker images and guides for using Torrust Index Frontend with docker for development and production.
78+
```s
79+
NUXT_PUBLIC_API_BASE="http://localhost:3001/v1" \
80+
NITRO_HOST="0.0.0.0" \
81+
NITRO_PORT="3000" \
82+
npm run dev
83+
```
84+
85+
> Please read our [container guide][containers] for more information.
86+
87+
### Production Version
88+
89+
You can run the production build in preview mode with the following:
90+
91+
```s
92+
npm install && npm run build && npm run preview
93+
```
94+
95+
### Services
96+
97+
The default configuration serves the web app on http://[::]:3000.
3698

3799
## Documentation
38100

39101
You can read the documentation [here](./docs/index.md).
40102

41103
## Contributing
42104

43-
We welcome contributions from the community!
105+
We are happy to support and welcome new people to our project. Please consider our [contributor guide][contribution_guide].</br>
106+
This is an open-source community-supported project. We welcome contributions from the community!
44107

45-
How can you contribute?
108+
__How can you contribute?__
46109

47110
* Bug reports and feature requests.
48-
* Code contributions. You can start by looking at the issues labeled ["good first issues"](https://github.com/torrust/torrust-index-gui/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
49-
* Documentation improvements. Check the [documentation](./docs/index.md) for typos, errors, or missing information.
50-
* Participation in the community. You can help by answering questions in the [discussions](https://github.com/torrust/torrust-index-gui/discussions).
111+
* Code contributions. You can start by looking at the issues labeled "[good first issues]".
112+
* Documentation improvements. Check the [documentation][docs] for typos, errors, or missing information.
113+
* Participation in the community. You can help by answering questions in the [discussions].
114+
115+
## License
51116

52-
Please report issues:
117+
**Copyright (c) 2023 The Torrust Developers.**
53118

54-
* Torrust Index Frontend specifically: [here](https://github.com/torrust/torrust-index-gui/issues).
55-
* Torrust Index in general: [here](https://github.com/torrust/torrust-index/issues).
119+
This program is free software: you can redistribute it and/or modify it under the terms of the [GNU Affero General Public License][AGPL_3_0] as published by the [Free Software Foundation][FSF], version 3.
56120

57-
Please read our [contribution agreement](https://github.com/torrust/.github/blob/main/info/contributing.md).
121+
This program is distributed in the hope that it will be useful, but __WITHOUT ANY WARRANTY__; without even the implied warranty of __MERCHANTABILITY__ or __FITNESS FOR A PARTICULAR PURPOSE__. See the [GNU Affero General Public License][AGPL_3_0] for more details.
58122

59-
## License
123+
You should have received a copy of the *GNU Affero General Public License* along with this program. If not, see <https://www.gnu.org/licenses/>.
124+
125+
Some files include explicit copyright notices and/or license notices.
126+
127+
### Legacy Exception
128+
129+
For prosperity, versions of Torrust Tracker that are older than five years are automatically granted the [MIT-0][MIT_0] license in addition to the existing [AGPL-3.0-only][AGPL_3_0] license.
130+
131+
### Contributor Agreement
132+
133+
The copyright of the Torrust Tracker is retained by the respective authors.
134+
135+
__Contributors agree:__
136+
137+
* That all their contributions be granted a license(s) __compatible__ with the [Torrust Trackers License](#license).
138+
* *That all contributors signal __clearly__ and __explicitly__ any other compilable licenses if they are not: *[AGPL-3.0-only with the legacy MIT-0 exception](#license)*.
139+
140+
**The Torrust-Tracker project has no copyright assignment agreement.**
60141

61-
The project is licensed under a dual license. See [COPYRIGHT](./COPYRIGHT).
142+
*We kindly ask you to take time and consider The Torrust Project [Contributor Agreement][agreement] in full.*
62143

63144
## Acknowledgments
64145

65-
This project was a joint effort by [Nautilus Cyberneering GmbH](https://nautilus-cyberneering.de/), [Dutch Bits](https://dutchbits.nl) and collaborators. Thank you to you all!
146+
This project was a joint effort by [Nautilus Cyberneering GmbH][nautilus], [Dutch Bits][Dutch Bits] and collaborators. Thank you to you all!
147+
148+
[AGPL_3_0]: ./LICENSE-AGPL_3_0
149+
[agreement]: https://github.com/torrust/.github/blob/main/info/licensing/contributor_agreement_v01.md
150+
[BEP_52]: https://www.bittorrent.org/beps/bep_0052.html
151+
[containers]: ./docs/index.md
152+
[contribution_guide]: https://github.com/torrust/.github/blob/main/info/contributing.md
153+
[discussions]: https://github.com/torrust/torrust-index-gui/discussions
154+
[dockerhub]: https://hub.docker.com/r/torrust/index-gui/tags
155+
[docs]: ./docs/index.md
156+
[Dutch Bits]: https://dutchbits.nl
157+
[FSF]: https://www.fsf.org/
158+
[MIT_0]: ./LICENSE-MIT_0
159+
[nautilus]: https://github.com/orgs/Nautilus-Cyberneering/

docs/containers.md renamed to docs/containerization_guide.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Containers (Docker or Podman)
1+
# Containerization Guide
22

33
- [Demo environment](#demo-environment)
44
- [Requirements](#requirements)
@@ -181,11 +181,11 @@ The format is: `--publish [optional_host_ip]:[host_port]:[container_port]/[optio
181181
The default ports can be mapped with the following (IPv4 and IPv6):
182182

183183
```s
184-
--publish 0.0.0.0:3000:3000/tcp \
185-
--publish [::]:3000:3000/tcp
184+
--publish "0.0.0.0:3000:3000/tcp" \
185+
--publish "[::]:3000:3000/tcp"
186186
```
187187

188-
> NOTE: Inside the container it is necessary to expose a socket with the wildcard address `0.0.0.0` so that it may be accessible from the host. Verify that the configuration that the sockets are wildcard.
188+
> NOTE: Inside the container it is necessary to expose a socket with the wildcard address `0.0.0.0` or `[::]` so that it may be accessible from the host. Verify that the configuration that the sockets are wildcard.
189189
190190
### Volumes
191191

0 commit comments

Comments
 (0)