Skip to content

Commit 5ae268f

Browse files
tdjsnellingtdjsnelling
committed
update readme, move config details to example file
1 parent cb011dd commit 5ae268f

3 files changed

Lines changed: 91 additions & 56 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@ Contributions to sqtracker are welcome. Trackers are often forked and modified,
44

55
## Code style
66

7-
Please follow existing conventions in code style. If you PR any messy, redundant or hard to understand code I will request changes on your PR.
7+
Please follow existing conventions in code style. If you PR any messy, redundant or hard to understand code then expect changes to be requested on your PR.
88

99
### Linting
1010

11-
All contributions **must** be linted with the existing `yarn lint` command. Better yet, use an editor or IDE that runs the linting for you, such as WebStorm. This will keep code style mostly consistent. Any un-linted PRs will have changes requested before I even review them.
11+
All contributions **must** be linted with the existing `yarn lint` command. Better yet, use an editor or IDE that runs the linting for you, such as WebStorm. This will keep code style mostly consistent.
1212

1313
### Comments
1414

‎README.md‎

Lines changed: 30 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -7,99 +7,80 @@ It implements all of the features required to run a private (or public) tracker
77
## Features
88

99
* Accounts
10-
* Registration modes (open/closed/invite only)
10+
* Registration modes (open / closed / invite only)
1111
* Sending of invites
1212
* Account management (2FA, password resets etc.)
1313
* Bonus points system
14+
* Option to browse torrents without logging in (for search engine discovery)
1415
* Torrent management
15-
* Uploading torrents with rich metadata (titles, descriptions, categories, tags etc.)
16+
* Uploading torrents with rich metadata (title, description, source, mediainfo, category, tags etc.)
1617
* Searching torrents or browsing by category or tags
1718
* Freeleech options (specific torrents, sitewide)
18-
* Upload/download tracking
19-
* Track how much content each user has uploaded/downloaded
19+
* Torrent grouping (e.g. different formats of same movie)
20+
* Bookmarks
21+
* Upload / download tracking
22+
* Track how much content each user has uploaded / downloaded
2023
* Track ratios
21-
* Limit up/downloading per user based on ratio
24+
* Limit up / downloading per user based on ratio
2225
* Award invites based on ratio
2326
* User interaction
2427
* Commenting on torrents
25-
* Up/down voting torrents
28+
* Up / down voting torrents
2629
* Requests system
2730
* Moderation
28-
* Staff/admin privileges
31+
* Staff / admin privileges
2932
* Reporting torrents to be reviewed by staff
3033
* Detailed stats available to admins
31-
* Announcements/news posts (for posting of tracker rules, important updates etc.)
32-
* Ban/unban users
34+
* Wiki system
35+
* Announcements / news posts
36+
* Ban / unban users
37+
* Tracker appearance
38+
* Configurable theme / CSS
3339

3440
## Deploying
3541

3642
### Components
3743

3844
An sqtracker deployment is made up of 4 separate components. These are:
3945

40-
#### A MongoDB database
41-
42-
[MongoDB](https://www.mongodb.com/) is a popular and powerful document-oriented database. Version 5.2 or higher is required.
43-
44-
#### The sqtracker API service
46+
#### 1. The sqtracker API service
4547

4648
The sqtracker API service handles all actions taken by users (authentication, uploads, searching etc.), implements the BitTorrent tracker specification to handle announces and scrapes, and provides the RSS feed.
4749

48-
#### The sqtracker client service
50+
#### 2. The sqtracker client service
4951

5052
The sqtracker client service provides the modern, responsive web interface that users interact with.
5153

52-
#### A HTTP proxy server
54+
#### 3. A MongoDB database
55+
56+
[MongoDB](https://www.mongodb.com/) is a popular and powerful document-oriented database. Version 5.2 or higher is required.
57+
58+
#### 4. A HTTP proxy server
5359

5460
The HTTP proxy allows the client, API, and BitTorrent tracker to all be accessible via a single endpoint.
5561

5662
### Deploying with Docker compose
5763

5864
The sqtracker platform is designed to be deployed via Docker. Once a configuration file is created, deploying is as simple as running `docker compose up -d` at the root of the project.
5965

66+
If you change the name of any services in `docker-compose.yml`, you will also need to update the relevant host names in your `config.js` and `traefik.yml` files.
67+
68+
sqtracker is reasonably light-weight, but you should still invest in a VPS with decent resources if you want to run a fast and performant tracker.
69+
70+
### Deploying with a PaaS platform
71+
6072
Alternatively, you can deploy each service individually on a PaaS cloud platform such as [Northflank](https://northflank.com).
6173

62-
If you change the name of any services in `docker-compose.yml`, you will also need to update the relevant host names in your `config.js` and `traefik.yml` files.
74+
You will need to deploy each of the 4 components listed above. The Docker images for the client and API services are published in this repository.
6375

6476
## Configuration
6577

6678
All configuration is provided via a single JavaScript file named `config.js`. This file must export an object containing 2 keys: `envs` and `secrets`.
6779

68-
A full list of configuration options is below. All are required.
80+
An example configuration can be found in `config.example.js`. This file contains examples and explanations for each config value.
6981

7082
If your configuration is not valid, sqtracker will fail to start.
7183

72-
| Key | Type | Example | Description |
73-
|----------------------------|---------|------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
74-
| SQ_SITE_NAME | envs | sqtracker demo | The name of your tracker site |
75-
| SQ_SITE_DESCRIPTION | envs | My very own private tracker | A short description of your tracker site |
76-
| SQ_THEME_COLOUR | envs | #f45d48 | A hex colour code used as the main theme colour of your site |
77-
| SQ_ALLOW_REGISTER | envs | `invite` | Registration mode. Either `open`, `invite` or `closed` |
78-
| SQ_ALLOW_ANONYMOUS_UPLOADS | envs | `false` | Whether or not users can upload torrents anonymously. Either `true` or `false` |
79-
| SQ_MINIMUM_RATIO | envs | 0.75 | Minimum allowed ratio. Below this users will not be able to download |
80-
| SQ_BP_EARNED_PER_GB | envs | 1 | Number of bonus points awarded to a user for each GB they upload |
81-
| SQ_BP_COST_PER_INVITE | envs | 3 | Number of bonus it costs a user to buy 1 invite (set to 0 to disable buying invites) |
82-
| SQ_BP_COST_PER_GB | envs | 3 | Number of bonus it costs a user to buy 1 GB of upload (set to 0 to disable buying upload) |
83-
| SQ_SITE_WIDE_FREELEECH | envs | `false` | Whether or not to enable freeleech on all torrents |
84-
| SQ_TORRENT_CATEGORIES | envs | `{ "Movies": ["HD", ...], "TV": [...] }` | A dictionary of categories, each with an array of zero or more sources available within that category |
85-
| SQ_ALLOW_UNREGISTERED_VIEW | envs | `false` | Whether or not torrent pages can be viewed by unregistered users. If true, only logged in users will be able to download/interact, but anyone (search engines included) will be able to view/read torrent info. |
86-
| SQ_BASE_URL | envs | https://demo.sqtracker.dev | The URL of your tracker site |
87-
| SQ_API_URL | envs | https://demo.sqtracker.dev/api | The URL of your API. Under the recommended setup, it should be `${SQ_BASE_URL}/api` |
88-
| SQ_MONGO_URL | envs | mongodb://sq_mongodb/sq | The URL of your MongoDB server. Under the recommended setup, it should be `mongodb://sq_mongodb/sq` |
89-
| SQ_MAIL_FROM_ADDRESS | envs | mail@sqtracker.dev | The address that mail will be sent from |
90-
| SQ_SMTP_HOST | envs | smtp.example.com | The hostname of your SMTP server |
91-
| SQ_SMTP_PORT | envs | 587 | The port of your SMTP server |
92-
| SQ_SMTP_SECURE | envs | `false` | Whether or not to force SMTP TLS: if true the connection will use TLS when connecting to server. If false (the default) then TLS is used if server supports the STARTTLS extension. In most cases set this value to true if you are connecting to port 465. For port 587 or 25 keep it false |
93-
| SQ_JWT_SECRET | secrets | — | A secret value to sign tokens with. Should be long and random |
94-
| SQ_SERVER_SECRET | secrets | — | A secret value to verify server requests with. Should be long and random, and different to the JWT secret |
95-
| SQ_ADMIN_EMAIL | secrets | admin@example.com | The email address to use for the initial admin user. Must be valid |
96-
| SQ_SMTP_USER | secrets | — | The username to authenticate with your SMTP server with |
97-
| SQ_SMTP_PASS | secrets | — | The password to authenticate with your SMTP server with |
98-
99-
### Example configuration
100-
101-
An example configuration can be found in `config.example.js`.
102-
10384
## Screenshots
10485

10586
Splash screen

‎config.example.js‎

Lines changed: 59 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,94 @@
1-
/*
2-
This is an example configuration file. Copy it to config.js and change each value according to your desired setup.
3-
See the README.md file for a description of each configuration item.
4-
*/
1+
// This is an example configuration file.
2+
// Copy it to config.js and change each value according to your desired setup.
53

64
module.exports = {
75
envs: {
6+
// The name of your tracker site. Maximum 20 characters.
87
SQ_SITE_NAME: "sqtracker demo",
8+
9+
// A short description of your tracker site. Maximum 80 characters.
910
SQ_SITE_DESCRIPTION: "A short description for your tracker site",
11+
12+
// A hex colour code used as the main theme colour of your site.
1013
SQ_THEME_COLOUR: "#f45d48",
14+
15+
// Registration mode. Either "open", "invite" or "closed".
16+
// Open: anyone can register.
17+
// Invite: must be invited by existing user.
18+
// Closed: no one can register.
1119
SQ_ALLOW_REGISTER: "invite",
20+
21+
// A boolean value determining whether users can choose to upload anonymously.
22+
// Admins can still see who uploaded anonymously, but other users cannot.
1223
SQ_ALLOW_ANONYMOUS_UPLOADS: false,
24+
25+
// Minimum allowed ratio. Below this users will not be able to download. Minimum 0.
1326
SQ_MINIMUM_RATIO: 0.75,
27+
28+
// A map of torrent categories that can be selected when uploading.
29+
// Each has an array of zero or more sources available within that category.
1430
SQ_TORRENT_CATEGORIES: {
1531
Movies: ["BluRay", "WebDL", "HDRip", "WebRip", "DVD", "Cam"],
1632
TV: [],
1733
Music: [],
1834
Books: [],
1935
},
36+
37+
// Number of bonus points awarded to a user for each GB they upload. Minimum 0.
2038
SQ_BP_EARNED_PER_GB: 1,
39+
40+
// Number of bonus it costs a user to buy 1 invite (set to 0 to disable buying invites).
2141
SQ_BP_COST_PER_INVITE: 3,
42+
43+
// Number of bonus it costs a user to buy 1 GB of upload (set to 0 to disable buying upload).
2244
SQ_BP_COST_PER_GB: 3,
45+
46+
// Whether to enable freeleech on all torrents.
2347
SQ_SITE_WIDE_FREELEECH: false,
48+
49+
// Whether torrent pages can be viewed by unregistered users.
50+
// If true, only logged-in users will be able to download/interact, but anyone (search engines included) will be able to view/read torrent info.
51+
// Enable if you want torrents to be indexed to help search traffic.
2452
SQ_ALLOW_UNREGISTERED_VIEW: false,
53+
54+
// The URL of your tracker site.
2555
SQ_BASE_URL: "https://sqtracker.dev",
56+
57+
// The URL of your API. Under the recommended setup, it should be `${SQ_BASE_URL}/api`.
2658
SQ_API_URL: "https://sqtracker.dev/api",
27-
SQ_MONGO_URL: "mongodb://sq_mongodb",
59+
60+
// The URL of your MongoDB server. Under the recommended setup, it should be `mongodb://sq_mongodb/sqtracker`.
61+
SQ_MONGO_URL: "mongodb://sq_mongodb/sqtracker",
62+
63+
// The email address that mail will be sent from.
2864
SQ_MAIL_FROM_ADDRESS: "mail@sqtracker.dev",
65+
66+
// The hostname of your SMTP server.
2967
SQ_SMTP_HOST: "smtp.example.com",
68+
69+
// The port of your SMTP server.
3070
SQ_SMTP_PORT: 587,
71+
72+
// Whether to force SMTP TLS: if true the connection will use TLS when connecting to server.
73+
// If false (the default) then TLS is used if server supports the STARTTLS extension.
74+
// In most cases set this value to true if you are connecting to port 465. For port 587 or 25 keep it false.
3175
SQ_SMTP_SECURE: false,
3276
},
3377
secrets: {
78+
// A secret value to sign tokens with. Should be long and random.
3479
SQ_JWT_SECRET: "long_random_string",
80+
81+
// A secret value to verify server requests with. Should be long and random, and different to the JWT secret.
3582
SQ_SERVER_SECRET: "another_long_random_string",
83+
84+
// The email address to use for the initial admin user.
85+
// Must be valid, you will need to verify.
3686
SQ_ADMIN_EMAIL: "admin@example.com",
87+
88+
// The username to authenticate with your SMTP server with.
3789
SQ_SMTP_USER: "smtp_username",
90+
91+
// The password to authenticate with your SMTP server with.
3892
SQ_SMTP_PASS: "smtp_password",
3993
},
4094
};

0 commit comments

Comments
 (0)