## File: doc/basics/docker.rst Running Tribler in Docker ========================= In order to run Tribler from docker you only need a few steps. We assume you have ``docker`` installed. Currently, only running the (unstable!) ``latest`` release is supported. Preparation ----------- Fetch the docker image from ``docker.io``: .. code-block:: docker pull tribler/tribler:latest Or, from ``ghcr.io``: .. code-block:: docker pull ghcr.io/tribler/tribler:latest Running ------- Choose a SECRET key for the background communication with Tribler. In the following example, we use the key ``changeme`` (don't use this yourself). To run the docker image: .. code-block:: docker run -e CORE_API_PORT=8085 -e CORE_API_KEY="changeme" \ -e LANG=C.UTF-8 \ -v ~/.Tribler:/home/ubuntu/.Tribler \ -v ~/downloads/TriblerDownloads:/home/ubuntu/Downloads \ -v $XDG_CACHE_HOME/tmp/:$XDG_CACHE_HOME/tmp/ -v /run:/run \ --security-opt "apparmor:unconfined" \ --net="host" \ -e XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR -e DISPLAY=$DISPLAY \ -e XDG_CACHE_HOME=$XDG_CACHE_HOME -e XAUTHORITY=$XAUTHORITY \ -e DBUS_SESSION_BUS_ADDRESS="$DBUS_SESSION_BUS_ADDRESS" \ --user $(id -u):$(id -g) -e BROWSER="x-www-browser" \ -it ghcr.io/tribler/tribler:latest *Alternatively*, if you want to run *without opening the web GUI* and *without a tray icon*: .. code-block:: docker run -e CORE_API_PORT=8085 -e CORE_API_KEY="changeme" \ -e LANG=C.UTF-8 \ -v ~/.Tribler:/home/ubuntu/.Tribler \ -v ~/downloads/TriblerDownloads:/home/ubuntu/Downloads \ --net="host" -it ghcr.io/tribler/tribler:latest -s You can then open Tribler in your web browser at the URL: .. code-block:: localhost:8085/ui/#/downloads/all?key=changeme Notes ----- This script binds the local "state" directory (this is where Tribler puts its internal files) to ``~/.Tribler`` and your downloads directory (where your downloads end up) to ``~/downloads/TriblerDownloads``. You can change these directories if you want to. If you're planning on manipulating Tribler's internal REST API, you can access it through ``http://localhost:8085/docs``. By default, the REST API is bound to localhost inside the container so to access the APIs, network needs to be set to host (--net="host"). Stopping -------- To stop Tribler, you should get the container id of your process and then stop it. You can view all active docker containers using ``docker ps`` and you can stop a container id using ``docker stop``. For most UNIX systems, the following command will stop your Tribler Docker container: .. code-block:: docker stop $(docker ps -aqf ancestor="ghcr.io/tribler/tribler:latest") --- ## File: doc/basics/running.rst Running Tribler from Source =========================== In order to run Tribler from its source you will need to perform some setup. We assume you have ``git`` and ``python`` installed. If you want to run a GUI for Tribler, you will need ``npm`` installed too. Steps ----- 1. Clone the Tribler repo: .. code-block:: git clone --recursive https://github.com/tribler/tribler .. warning:: Tribler uses submodules. If you (1) download the ZIP or (2) forget to recursively clone, your ``pyipv8`` folder will be empty. Repair the former by `downloading the IPv8 zip `_ and extracting it in the ``pyipv8`` folder and repair the latter by running ``git submodule update --init``. 2. Install the python dependencies: .. code-block:: python -m pip install --upgrade -r tribler/requirements.txt 3. Build the GUI: .. code-block:: cd src/tribler/ui/ npm install npm run build 4. Add the IPv8 submodule to your ``PYTHONPATH``. For example, (Windows) ``set PYTHONPATH=%PYTHONPATH%;pyipv8``, (Linux) ``export PYTHONPATH="${PYTHONPATH}:pyipv8"`` or (PyCharm) right click the ``pyipv8`` folder and ``Mark Directory as/Sources Root``. 5. Run Tribler: .. code-block:: cd src python run_tribler.py Sometimes, you may run into platform-specific issues. If this is your case, continue reading for your appropriate platform. --- ## File: doc/building/linux.rst Building on Linux ================= We assume you've set up your environment to run Tribler. Don't forget to build the GUI using NPM! Run the following commands in your terminal (assuming you are in the Tribler's repository root folder). First, install additional requirements: .. code-block:: sudo apt-get -y install alien devscripts fakeroot gir1.2-gtk-3.0 libgirepository1.0-dev rpm libcairo2-dev patchelf python -m pip install --upgrade -r build/requirements.txt Second, create the ``.deb`` file in the ``dist`` directory. You can set the ``GITHUB_TAG`` to whatever you want to have your version set as. .. code-block:: export GITHUB_TAG="1.2.3" ./build/debian/makedist_debian.sh --- ## File: doc/building/mac.rst Building on Mac =============== We assume you've set up your environment to run Tribler. Don't forget to build the GUI using NPM! Run the following commands in your terminal (assuming you are in the Tribler's repository root folder). First, install additional requirements: .. code-block:: python -m pip install -r build/requirements.txt Second, create the ``.dmg`` file in the ``dist`` directory. You can set the ``GITHUB_TAG`` to whatever you want to have your version set as. .. code-block:: export GITHUB_TAG="1.2.3" ./build/mac/makedist_macos.sh --- ## File: doc/building/windows.rst Building on Windows =================== We assume you've set up your environment to run Tribler. Don't forget to build the GUI using NPM! Additionally, you will need to install: - ``NSIS``, the ``SimpleFC`` plugin, and the ``nsProcess`` plugin. - ``Microsoft Visual Studio 2022 Enterprise``. ``2022 Community`` will also work, but you need to edit `tribler.nsi` in the appropriate place. - ``Windows Kits 10.0.26100.0``. - ``OpenSSL``. .. note:: If you install any of these applications to non-default folders, you will need to modify the build scripts. Run the following commands in your command prompt (assuming you are in the Tribler's repository root folder). First, install additional requirements: .. code-block:: python -m pip install -r build/requirements.txt Second, create the ``.exe`` file in the ``dist`` directory. You can set the ``GITHUB_TAG`` to whatever you want to have your version set as. .. code-block:: set GITHUB_TAG="1.2.3" build\win\makedist_win.bat --- ## File: doc/reference/software_architecture.rst Software Architecture ===================== This reference provides a high-level overview of Tribler's software architecture. The main entry point of Tribler is the ``run_tribler.py`` script and it has two main modes. The first mode launches Tribler with default settings. This causes a new browser tab to open that displays a web page generated with TypeScript. The second "headless" mode, does not open a browser tab. However, in both modes the core Tribler Python process runs. An overview of the most important functional components of Tribler is given in the following graph. We will provide a short description of each of these components. .. figure:: software_architecture.svg Session ------- The ``Session`` object (in ``session.py``) manages the core managers of Tribler: - The ``Notifier`` allows components to publish and subscribe to events. In some special cases, this is preferred over class inheritance or composition. Architectural spaghetti can sometimes be avoided by using ``Notifier`` events. - The ``TriblerConfigManager`` manages writing to and reading from user configuration files. This class manages defaults and the regeneration of (partially) missing configurations. - The ``DownloadManager`` allows management of torrent downloads. Functionality involves fetching torrent meta information, adding and removing downloads, and changing their anonymity level. - The ``RESTManager`` sets up a REST API. The API is used by Tribler's GUI, but can also be used programmatically by users in "headless" mode. - ``IPv8`` is used to manage peer-to-peer network overlays. All peer-to-peer traffic is handled by ``IPv8`` with the exception of non-anonymized torrent downloads. Functionality involves decentralized search and sharing popular torrents. - The ``IPv8CommunityLoader`` is used to launch all optional parts of Tribler. This includes launching ``IPv8`` overlays and registering REST API endpoints. The ``TriblerDatabase``, ``MetadataStore`` and the ``TorrentChecker`` are optionally available through the ``Session``. If requested, they are launched through the ``IPv8CommunityLoader``. Components ---------- The optional components of Tribler are given in ``components.py``. They can be divided into two groups: those that require a network overlay (inheriting from ``ComponentLauncher``) and those that do not (inheriting from ``ComponentLauncher``). Furthermore, the components can have complex relationships, like only launching after other components. The following list contains a high-level description of the components: - The ``DatabaseComponent`` is responsible for the two main databases. The first is the ``MetadataStore``, which stores all torrent and torrent tracker meta data and "health" (seeders and leechers). The second is the ``TriblerDatabase``, which stores torrent tags. - The ``TorrentCheckerComponent`` is responsible for retrieving the "health" information of torrents and trackers. This component may contact trackers for random torrents to determine whether they are reachable. The component also periodically updates the health information for known torrents based on tracker and DHT information. - The ``VersioningComponent`` is responsible for Tribler version management. Functionality includes upgrading data from local old Tribler versions to new Tribler versions and determining whether a new Tribler version has been published online. - The ``TunnelComponent`` allows for anonymization of torrent downloads. This component manages routing downloads over Tor-like circuits, including circuit construction and destruction. - The ``DHTDiscoveryComponent`` allows ``IPv8`` to decentrally search for overlays and peers with given public keys. - The ``ContentDiscoveryComment`` serves remote user searches and content popularity. Both outgoing and incoming user searches are served through this component. - The ``KnowledgeComponent`` handles extraction and search for torrent tags. - The ``RendezvousComponent`` keeps track of peers that have been connected to in the past. This is an experimental component that aims to serve as a source of decentral reputation. - The ``RecommenderComponent`` keeps track of local user searches and the preferred download for the search query. This is an experimental component that aims to serve as a source for Artificial Intelligence based personalized recommendations. Web UI ------ The Web UI serves to view and control the state of the Tribler process. Essentially, the Web UI uses three main classes: - The ``IPv8Service`` binds to the REST API of the ``IPv8`` component in the Tribler process. - The ``TriblerService`` binds to the REST API of anything that is not in the ``IPv8`` service. - The ``App`` is the React application entrypoint. The ``App`` contains a component to route information, the ``RouterProvider``, and a means to report errors that have been sent from the Tribler process. The architecture closely resembles the information in the GUI. Essentially, the ``RouterProvider`` mirrors the visible pages: - ``src/pages/Debug`` queries the Tribler process for debug information. - ``src/pages/Downloads`` includes components to render torrent downloads. - ``src/pages/Popular`` queries for popular torrents. - ``src/pages/Search`` manages pending searches, combining local and remote results. - ``src/pages/Settings`` reads and writes the Tribler configuration (through the REST API). --- ## File: doc/index.rst .. note:: Looking for user documentation? Check out https://www.tribler.org/howto.html Welcome to Tribler's developer documentation! ============================================= Tribler aims to give anonymous access to content. We are trying to make privacy, strong cryptography, and authentication the Internet norm. These documents specify how to run Tribler from the latest source code and how to build Tribler distributions. Table of contents ================= .. toctree:: :maxdepth: 2 :caption: Basics: basics/running.rst basics/docker.rst .. toctree:: :maxdepth: 2 :caption: Building: building/linux.rst building/mac.rst building/windows.rst .. toctree:: :maxdepth: 2 :caption: Reference: reference/software_architecture.rst Search ====== * :ref:`genindex` * :ref:`modindex` * :ref:`search` --- ## File: src/tribler/ui/README.md # Tribler web UI ## Getting started After checking out the Tribler repo, the web UI will not run out-of-the box. You'll either have to build the web UI or serve it from the Vite development server. Building the web UI works as follows: ``` cd src/tribler/ui/ npm install npm run build ``` This will create a `dist` folder which will automatically be served after Tribler restarts. Alternatively, while working on the web UI, it's often more convenient use the development server: ``` cd src/tribler/ui/ rm dist -r npm install npm run dev ``` After restarting Tribler, requests to `/ui` will be forwarded to the development server. Tribler assumes that the development server will run at `http://localhost:5173`. --- ## File: README.rst |doi| |openhub| |python_3_12| |contributors| |pr_closed| |issues_closed| | | .. raw:: html | *Alternative downloads:* - `flathub `_ |flathub| .. raw:: html For Fedora ≥ 42 and pure GNOME check out [this tray icon guide](https://github.com/Tribler/tribler/wiki/Enabling-the-Tray-icon-on-pure-GNOME). | ******* Tribler ******* Towards making Bittorrent anonymous and impossible to shut down. Tribler aims to give anonymous access to content. We are trying to make privacy, strong cryptography, and authentication the Internet norm. We implemented `our own enhanced Tor-like network for anonymous torrent downloading `_, with hidden services based seeding and end-to-end encryption. Since 2004, we have been working to ensure that "the only way to take Tribler down is to take The Internet down" (but a single software bug could end everything). Socials, Support and Contribution ================================= Want to hang out with other Tribler users? - Join our |discord| ! Have you found a bug or do you have a feature request? - If nobody else has already, `open an issue `_! Lost in development? - Check out our |docs| for development and building instructions! | | |downloads_pre_2006| |downloads_sourceforge| |downloads_github| | |latest_badge| |downloads_latest| ---- License ======= This file is part of Tribler, Copyright 2004-2024. Tribler is licensed under the GNU General Public License, version 3 (GPL-3.0), as published by the Free Software Foundation on 29 June 2007. Tribler is free software: you can redistribute it and/or modify it under the terms of this license. Tribler 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. For more details, see the full terms and conditions in the `LICENSE.txt `_ file at the root of this repository, or visit https://www.gnu.org/licenses/gpl-3.0.html. .. |pr_closed| image:: https://img.shields.io/github/issues-pr-closed/tribler/tribler.svg?style=flat :target: https://github.com/Tribler/tribler/pulls :alt: Pull Requests .. |issues_closed| image:: https://img.shields.io/github/issues-closed/tribler/tribler.svg?style=flat :target: https://github.com/Tribler/tribler/issues :alt: Issues .. |openhub| image:: https://www.openhub.net/p/tribler/widgets/project_thin_badge.gif?style=flat :target: https://www.openhub.net/p/tribler .. |downloads_pre_2006| image:: https://img.shields.io/badge/total_downloads_pre_2006-1.8M-brightgreen .. |downloads_sourceforge| image:: https://img.shields.io/badge/total_downloads_SourceForge-200k-brightgreen :target: https://sourceforge.net/projects/tribler/ .. |downloads_github| image:: https://img.shields.io/github/downloads/Tribler/tribler/total?label=total%20downloads%20GitHub :target: https://github.com/Tribler/tribler/releases .. |latest_badge| image:: https://img.shields.io/github/v/release/Tribler/tribler?label=latest&color=orange .. |downloads_latest| image:: https://img.shields.io/github/downloads/Tribler/tribler/latest/total?color=orange :target: https://github.com/Tribler/tribler/releases .. |contributors| image:: https://img.shields.io/github/contributors/tribler/tribler.svg?style=flat :target: https://github.com/Tribler/tribler/graphs/contributors :alt: Contributors .. |doi| image:: https://zenodo.org/badge/8411137.svg :target: https://zenodo.org/badge/latestdoi/8411137 :alt: DOI number .. |docs| image:: https://readthedocs.org/projects/tribler/badge/?version=latest :target: https://tribler.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status .. |discord| image:: https://img.shields.io/badge/discord-join%20chat-blue.svg :target: https://discord.gg/UpPUcVGESe :alt: Join Discord chat .. |python_3_12| image:: https://img.shields.io/badge/python-3.12-blue.svg :target: https://www.python.org/ .. |flathub| image:: https://img.shields.io/flathub/downloads/org.tribler.Tribler :alt: Flathub Downloads