Skip to content

Commit 585fbe7

Browse files
josecelanojosecelano
committed
docs: [#379] reorganize docs sections
1 parent 81422fd commit 585fbe7

File tree

5 files changed

+324
-338
lines changed

5 files changed

+324
-338
lines changed

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

Lines changed: 1 addition & 1 deletion
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)

‎docs/development_guide.md‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
# Development Guide
2+
3+
This is a guide to run the Torrust Index in development mode. It is not intended to be used in production.
4+
It runs all the services locally, so you can modify the code and see the changes immediately.
5+
You will need to run these three services:
6+
7+
- Torrust Tracker
8+
- Torrust Index Backend
9+
- Torrust Index Frontend
10+
11+
Before installing and running the services you can create a new directory to clone the repositories from GitHub.
12+
13+
```s
14+
cd /tmp
15+
mkdir torrust-index
16+
cd torrust-index/
17+
```
18+
19+
After installing all the repos you will have the following directory structure.
20+
21+
```s
22+
$ tree -L 2
23+
.
24+
├── torrust-index
25+
│   ├── adrs
26+
│   ├── bin
27+
│   ├── build.rs
28+
│   ├── Cargo.lock
29+
│   ├── Cargo.toml
30+
│   ├── CODEOWNERS
31+
│   ├── compose.yaml
32+
│   ├── config-idx-back.local.toml
33+
│   ├── config.local.toml
34+
│   ├── config.toml
35+
│   ├── config-tracker.local.toml
36+
│   ├── COPYRIGHT
37+
│   ├── cspell.json
38+
│   ├── data.db
39+
│   ├── docker
40+
│   ├── Dockerfile
41+
│   ├── docs
42+
│   ├── img
43+
│   ├── LICENSE-AGPL_3_0
44+
│   ├── LICENSE-MIT_0
45+
│   ├── licensing
46+
│   ├── migrations
47+
│   ├── project-words.txt
48+
│   ├── README.md
49+
│   ├── rustfmt.toml
50+
│   ├── src
51+
│   ├── storage
52+
│   ├── target
53+
│   ├── templates
54+
│   ├── tests
55+
│   └── upgrades
56+
├── torrust-index-gui
57+
│   ├── app.vue
58+
│   ├── assets
59+
│   ├── components
60+
│   ├── composables
61+
│   ├── COPYRIGHT
62+
│   ├── img
63+
│   ├── LICENSE-AGPL_3_0
64+
│   ├── LICENSE-MIT_0
65+
│   ├── licensing
66+
│   ├── node_modules
67+
│   ├── nuxt.config.ts
68+
│   ├── package.json
69+
│   ├── package-lock.json
70+
│   ├── pages
71+
│   ├── plugins
72+
│   ├── postcss.config.js
73+
│   ├── public
74+
│   ├── README.md
75+
│   ├── tailwind.config.js
76+
│   └── tsconfig.json
77+
└── torrust-tracker
78+
├── bin
79+
├── Cargo.lock
80+
├── Cargo.toml
81+
├── compose.yaml
82+
├── config.toml
83+
├── config.toml.local
84+
├── cSpell.json
85+
├── docker
86+
├── Dockerfile
87+
├── docs
88+
├── LICENSE
89+
├── NOTICE
90+
├── packages
91+
├── README.md
92+
├── rustfmt.toml
93+
├── SECURITY.md
94+
├── src
95+
├── storage
96+
├── target
97+
└── tests
98+
99+
34 directories, 41 files
100+
```
101+
102+
You can also run the Index GUI using the docker images for the Tracker and Index Backend.
103+
Please refer to their respective documentation for more information.
104+
105+
## Run the tracker
106+
107+
For the requirements please refer to the [Tracker documentation](https://github.com/torrust/torrust-tracker).
108+
109+
```s
110+
git clone git@github.com:torrust/torrust-tracker.git
111+
cd torrust-tracker
112+
mkdir -p ./storage/database
113+
./bin/install.sh
114+
cargo run
115+
```
116+
117+
```s
118+
Loading configuration from config file ./config.toml
119+
2023-06-21T14:55:03.270026920+01:00 [torrust_tracker::bootstrap::logging][INFO] logging initialized.
120+
2023-06-21T14:55:03.274190246+01:00 [torrust_tracker::bootstrap::jobs::tracker_apis][INFO] Starting Torrust APIs server on: http://127.0.0.1:1212
121+
2023-06-21T14:55:03.274292005+01:00 [torrust_tracker::bootstrap::jobs::tracker_apis][INFO] Torrust APIs server started
122+
```
123+
124+
Please refer to the [Tracker documentation](https://github.com/torrust/torrust-tracker) for more information.
125+
126+
## Run the backend
127+
128+
For the requirements please refer to the [Index documentation](https://github.com/torrust/torrust-index).
129+
130+
```s
131+
git clone git@github.com:torrust/torrust-index.git
132+
cd torrust-index/
133+
./contrib/dev-tools/init/install-local.sh
134+
TORRUST_INDEX_API_CORS_PERMISSIVE=true cargo run
135+
```
136+
137+
By default, the Index API has the most restrictive CORS policy. This means that the Index GUI cannot access the backend API, because they are running on different ports. If you run the backend as it is, you will see the following error in the browser console.
138+
139+
```s
140+
Access to fetch at 'http://localhost:3001/v1/torrents?page_size=50&page=0&sort=UploadedDesc&categories=&tags=' from origin 'http://localhost:3000' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
141+
```
142+
143+
You need to enable the Cors layer with the permissive option setting the environment variable `TORRUST_INDEX_API_CORS_PERMISSIVE` to `true`.
144+
145+
Please refer to the [Index documentation](https://github.com/torrust/torrust-index) for more information.
146+
147+
## Run the Index GUI
148+
149+
Requirements:
150+
151+
- Node: `^19.0.0`
152+
153+
```s
154+
git clone git@github.com:torrust/torrust-index-index-gui.git
155+
cd torrust-index-gui/
156+
./bin/install.sh
157+
npm run dev
158+
```
159+
160+
**NOTICE** Make sure the `.env` file is present in the root directory of the Index GUI. And contains the API URL.
161+
162+
```s
163+
API_BASE_URL=http://localhost:3001/v1
164+
```
165+
166+
After running `npm run dev` you should see something like this in the console.
167+
168+
```s
169+
Nuxi 3.0.0
170+
Nuxt 3.0.0 with Nitro 1.0.0
171+
> Local: http://localhost:3000/
172+
> Network: http://192.168.1.88:3000/
173+
174+
ℹ Using Tailwind CSS from ~/assets/css/tailwind.css
175+
ℹ Tailwind Viewer: http://localhost:3000/_tailwind/
176+
🌼 daisyUI components 2.51.5 https://daisyui.com
177+
✔︎ Including: base, components, 2 themes, utilities
178+
❤︎ Support daisyUI: https://opencollective.com/daisyui
179+
```
180+
181+
You can also see this warning in the console.
182+
183+
```s
184+
WARN Browserslist: caniuse-lite is outdated. Please run:
185+
npx update-browserslist-db@latest
186+
Why you should do it regularly: https://github.com/browserslist/update-db#readme
187+
```
188+
189+
You only need to follow the instructions and run `npx update-browserslist-db@latest`.
190+
191+
If you want to run the Index GUI like int production you can run the following command.
192+
193+
```s
194+
npm run build && npm run preview
195+
```
196+
197+
More information about the [nuxt]https://nuxt.com/) command can be found [here](https://nuxt.com/docs/api/commands/add).
198+
199+
## Testing
200+
201+
### Unit tests
202+
203+
We do not have nay unit tests yet. You can contribute by:
204+
205+
- [Setting up the scaffolding for unit testing](https://github.com/torrust/torrust-index-gui/issues/164).
206+
- Adding unit tests.
207+
208+
You can take a look at issues tagged with [testing](https://github.com/torrust/torrust-index-gui/issues?q=is%3Aissue+is%3Aopen+label%3Atesting).
209+
210+
### E2E tests
211+
212+
For now we only have E2E tests. We are starting to write E2E tests for the Index GUI. The [Index Index API](https://github.com/torrust/torrust-index/tree/develop/tests/e2e) has some tests, so part of the functionality is tested.
213+
214+
You can contribute adding more E2E tests. We are using this [issue](https://github.com/torrust/torrust-index-gui/issues/148) to track the tests we want to add.
215+
216+
In order to run the E2E test you need to have a running application at <http://localhost:3000>. There two important variables hardcoded in Cypress configuration file `cypress.config.ts`:
217+
218+
- The base URL: `http://localhost:3000` for the E2E testing environment.
219+
- The database file path: `./storage/database/torrust_index_backend_e2e_testing.db` for the E2E testing environment.
220+
221+
Those variables describe hot to access the system under test.
222+
223+
> **IMPORTANT** The database file path is relative to the root directory of the Index GUI. We should try to avoid this kind of dependencies. But for now, it is the easiest way to run the E2E tests. Ideally we should be able to run the test suit against any environment. For example, we should be able to run the test suit against an staging environment. That's still possible if we are running the tests from a machine that has access to the filesystem environment or we could start running the test using MySQL SQLite.
224+
225+
The Cypress configuration file looks like this:
226+
227+
```TypeScript
228+
export default defineConfig({
229+
e2e: {
230+
baseUrl: "http://localhost:3000",
231+
setupNodeEvents (on, config) {
232+
on("task", {
233+
grantAdminRole: ({ username }) => {
234+
return grantAdminRole(username, databaseConfig(config));
235+
}
236+
});
237+
}
238+
},
239+
env: {
240+
db_file_path: "./storage/database/torrust_index_backend_e2e_testing.db"
241+
}
242+
});
243+
```
244+
245+
The database file path (`db_file_path`) is needed because some tests need to access the database directly. For example, the test that grants the admin role to a user. There is no way to create administrator users using the Index GUI. So, we need to do it directly in the database.
246+
247+
You can run the E2E test environments in two different ways:
248+
249+
- Using docker compose.
250+
- Running the Tracker, Index and the Index GUI locally (development environment).
251+
252+
If you want to use the docker-compose environment you need to run the following command:
253+
254+
```s
255+
./contrib/dev-tools/container/e2e/sqlite/run-e2e-tests.sh
256+
```
257+
258+
This is the way we run the E2E tests in the CI/CD pipeline.
259+
260+
You should use the development environment if you want to debug the E2E tests or you are writing tests and code at the same time.
261+
262+
**NOTICE** You will need to change the database file path in the Index to use the same as in the Index GUI so the running Index and the Cypress tests can access the same database. For example, change the database `connect_url` value in the Index config file to `"sqlite://../torrust-index-gui/storage/index/lib/database/e2e_testing_sqlite3.db?mode=rwc"` or whatever the path is in your machine.
263+
264+
Once the E2E environment is up, you can run the E2E tests with the following command.
265+
266+
```s
267+
npm run cypress:run
268+
```
269+
270+
With that command you will use the headless browser. If you want to see the browser while the tests are running you can run the following command:
271+
272+
```s
273+
npm run cypress:open
274+
```
275+
276+
Please refer to the [Cypress documentation](https://docs.cypress.io/) for more information.
277+
278+
If you want to contribute please read the [Cypress Best Practices](https://docs.cypress.io/guides/references/best-practices) documentation.

0 commit comments

Comments
 (0)