Getting Started

⚡ Quick Start Guide

Important

This section contains just enough information to get started using this project, and is by no means the most optimal configuration. It is advised to read the Basic Setup Guide.

1. Clone the repo.

user@linux:~/Downloads$ git clone https://github.com/DitherDude/browser
Cloning into 'browser'...
...
Resolving deltas: 100% (?/?), done.

2. Ensure you have rustup installed.

user@linux:~$ rustc -V && cargo -V && rustup -V
rustc 1.88.0
cargo 1.88.0
rustup 1.28.2
info: ...

Note

If rustup is not installed, install it.

user@linux:~$ rustc -V && cargo -V && rustup -V
rustc: command not found
user@linux:~$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Client

Note

Use this if you wish to visit websites.

3. Build and run the frontend binary.

user@linux:~/Downloads/browser$ cargo run --bin frontend

Warning

As of writing, backend (a library used by frontend) expects the DNS provider and DNS cacher to be hosted on 0.0.0.0:6202 and 0.0.0.0:6203, respectively.

This should result in the following error if executed successfully:

    Finished
ERROR frontend: No stacks found!
user@linux:~/Downloads/browser$

This is due to how the browser is designed to present webpages. Use the following command to compile any parser in this repo:

Tip

Replace mdparser with the stacks parser you wish to compile. See Bundled Stacks (will link) for a full list of included stack parsers. You can also copy external stacks libraries into the folder that the frontend executable is located. In this example, it is ~/Downloads/browser/target/debug

user@linux:~/Downloads/browser$ cargo build -p mdparser
    Finished
user@linux:~/Downloads/browser$

Caution

Placing arbitrary libraries here may cause MALICIOUS CODE EXECUTION. Make sure you trust the developer of the stacks libraries before you add any of their libraries to the directory of the frontend executable. It is recommended to make this directory read-only.

4. As you have modified your parsers, make sure to notify frontend that there has been a change.

user@linux:~/Downloads/browser$ cargo run --bin frontend -- --refresh-stacks
WARN frontend: Overwriting stacks DB

Server

Note

Use this if you wish to host websites.

3. Build and run the server binary.

Tip

Replace /path/to/website with the path to the main folder that contains all your website files.

user@linux:~/Downloads/browser$ cargo run --bin server -- --directory /path/to/website

Caution

Anyone who can access your website can view ALL THE FILES IN THE SPECIFIED DIRECTORY AND ITS SUBDIRECTORIES. It is recommended to isolate this folder to avoid potential data leaks. These files are still write-protected.

This should result in the following error if executed successfully:

    Finished
ERROR server: Cannot find stacks file:
user@linux:~/Downloads/browser$

The server expects a stacks.txt file in the root directory (in this example, /path/to/website/stacks.txt). See Creating a stacks.txt File for information on how to construct this file. Once you have created a stacks.txt file, re-run the above command.

user@linux:~/Downloads/browser$ cargo run --bin server -- --directory /path/to/website
INFO server: Listening on port 6204. Server setup OK!

Once your website is live, you will need to register a URL so that a dns_provider and dns_cacher can point to your website. See Obtaining a URL (will link).

DNS Provider

Note

Use this if you wish to host a block in the URL hierarchy chain.

3. Build and run the dns_provider binary.

user@linux:~/Downloads/browser$ cargo run --bin dns_provider
    Finished
INFO dns_provider: Listening on port 6202. Server setup OK!

Make sure you have allowed port 6202 through your firewall.

Note

This expects a MySQL database at mysql://root:password@localhost:3306/dns. If you are hosting the database elsewhere, specify the URL with

user@linux:~/Downloads/browser$ cargo run --bin dns_provider -- --sql-url mysql://user:pass@URL:port/database

where mysql://user:pass@URL:port/database is the database location.

DNS Cacher

Note

Use this if you wish to host a FQDN URL cache. See DNS Provider VS DNS Cacher (will link) for information on the discrepancies between the two binaries.

3. Build and run the dns_cacher binary.

user@linux:~/Downloads/browser$ cargo run --bin dns_cacher
    Finished
INFO dns_cacher: Listening on port 6203. Server setup OK!

Make sure you have allowed port 6203 through your firewall.

Note

This expects a MySQL database at mysql://root:password@localhost:3306/dns. If you are hosting the database elsewhere, specify the URL with

user@linux:~/Downloads/browser$ cargo run --bin dns_cacher -- --sql-url mysql://user:pass@URL:port/database

where mysql://user:pass@URL:port/database is the database location.

Basic Setup Guide

Flags

Flags are the parameters passed into the executable binaries at runtime. Each full-named flag has an associated short-named flag with identical functionality. Note that some refinement may only be possible through short-named flags. See Binary Flags (will link) to gain a better understanding of how flags work across all DitherDude projects.

Currently Supported Flags

Binary	Short Name	Long Name	Expects	Required	Default	Usage
any	v	verbose	-	No	INFO	Each instance of this flag bumps the logging level down by one, and likewise the verbosity up by one. (INFO => DEBUG => TRACE).
frontend	c	no-caching	-	No	true	Disables using a local cache.db to store and lookup FQDN URLs. (false => no caching). Caching can cause pre-visited websites to load faster, at the cost of storage space.
frontend	d	data-saver	-	No	false	Enables data saving optimisations. (true => use data saving optimisations). Currently, this disables the pre-loading of websites while you are typing into the addressbar. Note this option harms performace at the cost of saving Internet data.
frontend	r	refresh-stacks	-	No	false	Forces frontend to re-scan for all stacks libraries, even if the stacks.db file exists. (true => force refresh stacks). Note that this is automatically run if the stacks.db file does not exist, and no stacks are provided in the stacks flag.
frontend	S	stacks	String	No	-	Forces the stacks list to the specified string. This can be helpful to re-order the stacks sequence without modifying the stacks.db file.
frontend	s	-	String	No	-	Appends the specified string to the stacks list. Note this differs from the above flag by not overwriting the stacks list.
server	d	directory	String	Yes	-	The folder which the website is hosted within.
server	p	port	u32	No	6204	The port server is to run on.
server	s	stacks	String	No	-	The location of the stacks file. See Creating a stacks.txt File.
dns_provider	o	overwrite	-	No	false	Whether to overwrite the dns_records table if it is structurally misconfigured. (true => overwrite erroneous dns_records table). Ill-advised to run, as it may cause potential data loss.
dns_provider	p	port	u32	No	6202	The port dns_provider is to run on.
dns_provider	s	sql-url	String	No	mysql:// root:password@ localhost:3306/dns	The url for the database to host the dns_records table.
dns_cacher	o	overwrite	-	No	false	Whether to overwrite the dns_cache table if it is structurally misconfigured. (true => overwrite erroneous dns_cache table). Ill-advised to run, as it may cause potential data loss.
dns_cacher	p	port	u32	No	6203	The port dns_cacher is to run on.
dns_cacher	s	sql-url	String	No	mysql:// root:password@ localhost:3306/dns	The url for the database to host the dns_cache table.