mirror of
https://github.com/neon-mmd/websurfx.git
synced 2024-11-25 07:28:22 -05:00
docs: move docs from wiki to docs folder & add an image for docs
This commit is contained in:
neon_arch
parent
3c313543f3
commit
0d271a0fcf
17
docs/README.md
Normal file
17
docs/README.md
Normal file
@ -0,0 +1,17 @@
|
|||||||
|
<h1 align="center"><img src="../images/websurfx_docs_image.png" alt="Websurfx Docs" align="center"></h1>
|
||||||
|
|
||||||
|
# General
|
||||||
|
|
||||||
|
- [Introduction](./introduction.md)
|
||||||
|
- [**FAQ**](./faq.md)
|
||||||
|
|
||||||
|
# Users
|
||||||
|
|
||||||
|
- [Installation](./installation.md)
|
||||||
|
- [Configuration](./configuration.md)
|
||||||
|
- [Theming](./theming.md)
|
||||||
|
|
||||||
|
# Developers
|
||||||
|
|
||||||
|
- [**Contribute**](https://github.com/neon-mmd/websurfx/blob/master/CONTRIBUTING.md)
|
||||||
|
- [**Coding style**](https://rust-lang.github.io/api-guidelines/naming.html)
|
||||||
42
docs/configuration.md
Normal file
42
docs/configuration.md
Normal file
@ -0,0 +1,42 @@
|
|||||||
|
# Configuration
|
||||||
|
|
||||||
|
Everything in websurfx can be configured through the config file located at `websurfx/config.lua`.
|
||||||
|
|
||||||
|
Some of the configuration options provided in the file are stated below. These are subdivided into three categories:
|
||||||
|
|
||||||
|
- Server
|
||||||
|
- Website
|
||||||
|
- Cache
|
||||||
|
|
||||||
|
## Server
|
||||||
|
|
||||||
|
- **port:** Port number on which server should be launched.
|
||||||
|
- **binding_ip_addr:** IP address on the which server should be launched.
|
||||||
|
|
||||||
|
## Website
|
||||||
|
|
||||||
|
- **colorscheme:** The colorscheme name which should be used for the website theme (the name should be in accordance to the colorscheme file name present in `public/static/colorschemes` folder).
|
||||||
|
|
||||||
|
> By Default we provide 9 colorschemes to choose from these are:
|
||||||
|
>
|
||||||
|
> 1. catppuccin-mocha
|
||||||
|
> 2. dracula
|
||||||
|
> 3. monokai
|
||||||
|
> 4. nord
|
||||||
|
> 5. oceanic-next
|
||||||
|
> 6. solarized-dark
|
||||||
|
> 7. solarized-light
|
||||||
|
> 8. tomorrow-night
|
||||||
|
> 9. gruvbox-dark
|
||||||
|
|
||||||
|
- **theme:** The theme name which should be used for the website (again, the name should be in accordance to the theme file name present in `public/static/themes` folder).
|
||||||
|
|
||||||
|
> By Default we provide 1 theme to choose from these are:
|
||||||
|
>
|
||||||
|
> 1. simple
|
||||||
|
|
||||||
|
## Cache
|
||||||
|
|
||||||
|
- **redis_connection_url:** Redis connection url address on which the client should connect on.
|
||||||
|
|
||||||
|
[⬅️ Go back to Home](https://github.com/neon-mmd/websurfx/wiki).
|
||||||
15
docs/faq.md
Normal file
15
docs/faq.md
Normal file
@ -0,0 +1,15 @@
|
|||||||
|
# General Questions
|
||||||
|
|
||||||
|
## Why Websurfx?
|
||||||
|
|
||||||
|
The main goal of the Websurfx project is to provide a fast, secure, and privacy-focused [meta search engine](https://en.wikipedia.org/wiki/Metasearch_engine). While there are many meta search engines available, they do not always guarantee the security of their search engine, which is essential for ensuring privacy. For example, memory vulnerabilities can leak private or sensitive information, which is never good. Websurfx is written in Rust, which guarantees memory safety and eliminates such problems. Many meta search engines also lack key features such as advanced image search, which is required by many graphic designers, content creators, and others. Websurfx aims to provide these features and others, such as proper NSFW blocking, to improve the user experience.
|
||||||
|
|
||||||
|
## Why AGPLv3?
|
||||||
|
|
||||||
|
Websurfx is released under the AGPLv3 license to ensure that the source code remains open and transparent. This helps to prevent the inclusion of spyware, telemetry, or other malicious code in the project. AGPLv3 is a strong copyleft license that ensures the source code of the software remains open and available to everyone, including any modifications or improvements made to the code.
|
||||||
|
|
||||||
|
## Why Rust?
|
||||||
|
|
||||||
|
Rust was chosen as the programming language for Websurfx due to its memory safety features, which can help prevent vulnerabilities and make the codebase more secure. Rust is also faster than C++, which helps to make Websurfx fast and responsive. In addition, Rust's ownership and borrowing system allows for safe concurrency and thread safety in the codebase.
|
||||||
|
|
||||||
|
[⬅️ Go back to Home](https://github.com/neon-mmd/websurfx/wiki).
|
||||||
85
docs/installation.md
Normal file
85
docs/installation.md
Normal file
@ -0,0 +1,85 @@
|
|||||||
|
# Stable
|
||||||
|
|
||||||
|
To get started with Websurfx, clone the repository, edit the config file which is located in the `websurfx` directory and install redis server by following the instructions located [here](https://redis.io/docs/getting-started/) and then run the websurfx server and redis server using the following commands:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git clone https://github.com/neon-mmd/websurfx.git
|
||||||
|
cd websurfx
|
||||||
|
cargo build
|
||||||
|
redis-server --port 8082 &
|
||||||
|
./target/debug/websurfx
|
||||||
|
```
|
||||||
|
|
||||||
|
# Rolling/Edge/Unstable
|
||||||
|
|
||||||
|
If you want to use the rolling/edge branch, run the following commands instead:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git clone https://github.com/neon-mmd/websurfx.git
|
||||||
|
cd websurfx
|
||||||
|
git checkout rolling
|
||||||
|
cargo build
|
||||||
|
redis-server --port 8082 &
|
||||||
|
./target/debug/websurfx
|
||||||
|
```
|
||||||
|
|
||||||
|
Once you have started the server, open your preferred web browser and navigate to http://127.0.0.1:8080/ to start using Websurfx.
|
||||||
|
|
||||||
|
# Docker Deployment
|
||||||
|
|
||||||
|
Before you start, you will need [Docker](https://docs.docker.com/get-docker/) installed on your system first.
|
||||||
|
|
||||||
|
## Stable
|
||||||
|
|
||||||
|
First clone the the repository by running the following command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/neon-mmd/websurfx.git
|
||||||
|
cd websurfx
|
||||||
|
```
|
||||||
|
|
||||||
|
After that edit the config.lua file located under `websurfx` directory. In the config file you will specifically need to change to values which is `binding_ip_addr` and `redis_connection_url` which should make the config look something like this:
|
||||||
|
|
||||||
|
```lua
|
||||||
|
-- Server
|
||||||
|
port = "8080" -- port on which server should be launched
|
||||||
|
binding_ip_addr = "0.0.0.0" --ip address on the which server should be launched.
|
||||||
|
|
||||||
|
-- Website
|
||||||
|
-- The different colorschemes provided are:
|
||||||
|
-- {{
|
||||||
|
-- catppuccin-mocha
|
||||||
|
-- dracula
|
||||||
|
-- monokai
|
||||||
|
-- nord
|
||||||
|
-- oceanic-next
|
||||||
|
-- solarized-dark
|
||||||
|
-- solarized-light
|
||||||
|
-- tomorrow-night
|
||||||
|
-- }}
|
||||||
|
colorscheme = "catppuccin-mocha" -- the colorscheme name which should be used for the website theme
|
||||||
|
theme = "simple" -- the theme name which should be used for the website
|
||||||
|
|
||||||
|
-- Caching
|
||||||
|
redis_connection_url = "redis://redis:6379" -- redis connection url address on which the client should connect on.
|
||||||
|
```
|
||||||
|
|
||||||
|
After this run the following command to deploy the app:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
This will take around 5-10 mins for first deployment, afterwards the docker build stages will be cached so it will be faster to be build from next time onwards. After the above step finishes launch your preferred browser and then navigate to `http://<ip_address_of_the_device>:<whatever_port_you_provided_in_the_config>`.
|
||||||
|
|
||||||
|
## Unstable/Edge/Rolling
|
||||||
|
|
||||||
|
For the unstable/rolling/edge version, follow the same steps as above with an addition of one command for cloning the repository which makes the cloning step as follows:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/neon-mmd/websurfx.git
|
||||||
|
cd websurfx
|
||||||
|
git checkout rolling
|
||||||
|
```
|
||||||
|
|
||||||
|
[⬅️ Go back to Home](https://github.com/neon-mmd/websurfx/wiki).
|
||||||
13
docs/introduction.md
Normal file
13
docs/introduction.md
Normal file
@ -0,0 +1,13 @@
|
|||||||
|
# Introduction
|
||||||
|
|
||||||
|
A modern-looking, lightning-fast, privacy-respecting, secure [meta search engine](https://en.wikipedia.org/wiki/Metasearch_engine) (pronounced as websurface or web-surface /wɛbˈsɜːrfəs/.) written in Rust. It provides a fast and secure search experience while respecting user privacy.
|
||||||
|
|
||||||
|
# Motivation
|
||||||
|
|
||||||
|
Most meta search engines tend to be slow, lack high level of customization and missing many features and all of them like security as they are written in unsafe languages like python, javascript, etc which tend to open a wide variety of vulnerabilities which can also sometimes pose a threat to privacy as sometimes this can be exploited and can be used to leveraged to leak out sensitive information which is never good.
|
||||||
|
|
||||||
|
# Solution
|
||||||
|
|
||||||
|
Websurfx is a project which seeks to provide privacy, security, speed and all the features which the user wants.
|
||||||
|
|
||||||
|
[⬅️ Go back to Home](https://github.com/neon-mmd/websurfx/wiki).
|
||||||
324
docs/theming.md
Normal file
324
docs/theming.md
Normal file
@ -0,0 +1,324 @@
|
|||||||
|
# Colorschemes
|
||||||
|
|
||||||
|
## Built-in
|
||||||
|
|
||||||
|
By default `websurfx` comes with 9 colorschemes to choose from which can be easily chosen using the config file. To how to change colorschemes please view the [Configuration](https://github.com/neon-mmd/websurfx/wiki/configuration) section of the wiki.
|
||||||
|
|
||||||
|
## Custom
|
||||||
|
|
||||||
|
Creating coloschemes is as easy as it gets it requires the user to have a theme file name with the colorscheme in which every space should be replaced with a `-` (dash) and it should end with a `.css` file extension. After creating the file you need to add the following code with the `colors` you want:
|
||||||
|
|
||||||
|
``` css
|
||||||
|
:root{
|
||||||
|
--bg: <background color>;
|
||||||
|
--fg: <foreground color (text color)>;
|
||||||
|
--1: <color 1>;
|
||||||
|
--2: <color 2>;
|
||||||
|
--3: <color 3>;
|
||||||
|
--4: <color 4>;
|
||||||
|
--5: <color 5>;
|
||||||
|
--6: <color 6>;
|
||||||
|
--7: <color 7>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Note**
|
||||||
|
> Please infer the theme file located under `public/static/themes` to better understand where each color is being used.
|
||||||
|
|
||||||
|
**Example of `catppuccin-mocha` colorscheme:**
|
||||||
|
|
||||||
|
``` css
|
||||||
|
:root {
|
||||||
|
--bg: #1e1e2e;
|
||||||
|
--fg: #cdd6f4;
|
||||||
|
--1: #45475a;
|
||||||
|
--2: #f38ba8;
|
||||||
|
--3: #a6e3a1;
|
||||||
|
--4: #f9e2af;
|
||||||
|
--5: #89b4fa;
|
||||||
|
--6: #f5c2e7;
|
||||||
|
--7: #ffffff;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
# Themes
|
||||||
|
|
||||||
|
## Built-in
|
||||||
|
|
||||||
|
By default `websurfx` comes with 1 theme to choose from which can be easily chosen using the config file. To how to change themes please view the [Configuration](https://github.com/neon-mmd/websurfx/wiki/configuration) section of the wiki.
|
||||||
|
|
||||||
|
## Custom
|
||||||
|
|
||||||
|
To write custom color scheme, it requires the user to have some knowledge of `css stylesheets`.
|
||||||
|
|
||||||
|
**Here is an example of `simple theme` (which we provide by default with the app) which will give the user a better idea on how to create a custom theme using it as a template:**
|
||||||
|
|
||||||
|
### General
|
||||||
|
``` css
|
||||||
|
* {
|
||||||
|
padding: 0;
|
||||||
|
margin: 0;
|
||||||
|
box-sizing: border-box;
|
||||||
|
}
|
||||||
|
|
||||||
|
html {
|
||||||
|
font-size: 62.5%;
|
||||||
|
}
|
||||||
|
|
||||||
|
body {
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
justify-content: space-between;
|
||||||
|
align-items: center;
|
||||||
|
height: 100vh;
|
||||||
|
background: var(--1);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
### Styles for the index page
|
||||||
|
``` css
|
||||||
|
.search-container {
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
gap: 5rem;
|
||||||
|
justify-content: center;
|
||||||
|
align-items: center;
|
||||||
|
}
|
||||||
|
|
||||||
|
.search-container div {
|
||||||
|
display: flex;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
### Styles for the search box and search button
|
||||||
|
``` css
|
||||||
|
.search_bar {
|
||||||
|
display: flex;
|
||||||
|
}
|
||||||
|
|
||||||
|
.search_bar input {
|
||||||
|
padding: 1rem;
|
||||||
|
width: 50rem;
|
||||||
|
height: 3rem;
|
||||||
|
outline: none;
|
||||||
|
border: none;
|
||||||
|
box-shadow: rgba(0, 0, 0, 1);
|
||||||
|
background: var(--fg);
|
||||||
|
}
|
||||||
|
|
||||||
|
.search_bar button {
|
||||||
|
padding: 1rem;
|
||||||
|
border-radius: 0;
|
||||||
|
height: 3rem;
|
||||||
|
display: flex;
|
||||||
|
justify-content: center;
|
||||||
|
align-items: center;
|
||||||
|
outline: none;
|
||||||
|
border: none;
|
||||||
|
gap: 0;
|
||||||
|
background: var(--bg);
|
||||||
|
color: var(--3);
|
||||||
|
font-weight: 600;
|
||||||
|
letter-spacing: 0.1rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.search_bar button:active,
|
||||||
|
.search_bar button:hover {
|
||||||
|
filter: brightness(1.2);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
### Styles for the footer and header
|
||||||
|
``` css
|
||||||
|
header {
|
||||||
|
background: var(--bg);
|
||||||
|
width: 100%;
|
||||||
|
display: flex;
|
||||||
|
justify-content: right;
|
||||||
|
align-items: center;
|
||||||
|
padding: 1rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
header ul,
|
||||||
|
footer ul {
|
||||||
|
list-style: none;
|
||||||
|
display: flex;
|
||||||
|
justify-content: space-around;
|
||||||
|
align-items: center;
|
||||||
|
font-size: 1.5rem;
|
||||||
|
gap: 2rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
header ul li a,
|
||||||
|
footer ul li a,
|
||||||
|
header ul li a:visited,
|
||||||
|
footer ul li a:visited {
|
||||||
|
text-decoration: none;
|
||||||
|
color: var(--2);
|
||||||
|
text-transform: capitalize;
|
||||||
|
letter-spacing: 0.1rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
header ul li a {
|
||||||
|
font-weight: 600;
|
||||||
|
}
|
||||||
|
|
||||||
|
header ul li a:hover,
|
||||||
|
footer ul li a:hover {
|
||||||
|
color: var(--5);
|
||||||
|
}
|
||||||
|
|
||||||
|
footer div span {
|
||||||
|
font-size: 1.5rem;
|
||||||
|
color: var(--4);
|
||||||
|
}
|
||||||
|
|
||||||
|
footer div {
|
||||||
|
display: flex;
|
||||||
|
gap: 1rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
footer {
|
||||||
|
background: var(--bg);
|
||||||
|
width: 100%;
|
||||||
|
padding: 1rem;
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
justify-content: center;
|
||||||
|
align-items: center;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
### Styles for the search page
|
||||||
|
``` css
|
||||||
|
.results {
|
||||||
|
width: 90%;
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
justify-content: space-around;
|
||||||
|
}
|
||||||
|
|
||||||
|
.results .search_bar {
|
||||||
|
margin: 1rem 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.results_aggregated {
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
justify-content: space-between;
|
||||||
|
margin: 2rem 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.results_aggregated .result {
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
margin-top: 1rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.results_aggregated .result h1 a {
|
||||||
|
font-size: 1.5rem;
|
||||||
|
color: var(--2);
|
||||||
|
text-decoration: none;
|
||||||
|
letter-spacing: 0.1rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.results_aggregated .result h1 a:hover {
|
||||||
|
color: var(--5);
|
||||||
|
}
|
||||||
|
|
||||||
|
.results_aggregated .result h1 a:visited {
|
||||||
|
color: var(--bg);
|
||||||
|
}
|
||||||
|
|
||||||
|
.results_aggregated .result small {
|
||||||
|
color: var(--3);
|
||||||
|
font-size: 1.1rem;
|
||||||
|
word-wrap: break-word;
|
||||||
|
line-break: anywhere;
|
||||||
|
}
|
||||||
|
|
||||||
|
.results_aggregated .result p {
|
||||||
|
color: var(--fg);
|
||||||
|
font-size: 1.2rem;
|
||||||
|
margin-top: 0.3rem;
|
||||||
|
word-wrap: break-word;
|
||||||
|
line-break: anywhere;
|
||||||
|
}
|
||||||
|
|
||||||
|
.results_aggregated .result .upstream_engines {
|
||||||
|
text-align: right;
|
||||||
|
font-size: 1.2rem;
|
||||||
|
padding: 1rem;
|
||||||
|
color: var(--5);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Styles for the 404 page
|
||||||
|
|
||||||
|
``` css
|
||||||
|
.error_container {
|
||||||
|
display: flex;
|
||||||
|
justify-content: center;
|
||||||
|
align-items: center;
|
||||||
|
width: 100%;
|
||||||
|
gap: 5rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.error_container img {
|
||||||
|
width: 30%;
|
||||||
|
}
|
||||||
|
|
||||||
|
.error_content {
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
justify-content: center;
|
||||||
|
gap: 1rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.error_content h1,
|
||||||
|
.error_content h2 {
|
||||||
|
letter-spacing: 0.1rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.error_content h1 {
|
||||||
|
font-size: 3rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.error_content h2 {
|
||||||
|
font-size: 2rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.error_content p {
|
||||||
|
font-size: 1.2rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
.error_content p a,
|
||||||
|
.error_content p a:visited {
|
||||||
|
color: var(--2);
|
||||||
|
text-decoration: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.error_content p a:hover {
|
||||||
|
color: var(--5);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
### Styles for the previous and next button on the search page
|
||||||
|
``` css
|
||||||
|
.page_navigation {
|
||||||
|
padding: 0 0 2rem 0;
|
||||||
|
display: flex;
|
||||||
|
justify-content: space-between;
|
||||||
|
align-items: center;
|
||||||
|
}
|
||||||
|
|
||||||
|
.page_navigation button {
|
||||||
|
background: var(--bg);
|
||||||
|
color: var(--fg);
|
||||||
|
padding: 1rem;
|
||||||
|
border-radius: 0.5rem;
|
||||||
|
outline: none;
|
||||||
|
border: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.page_navigation button:active {
|
||||||
|
filter: brightness(1.2);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
[⬅️ Go back to Home](https://github.com/neon-mmd/websurfx/wiki).
|
||||||
BIN
images/websurfx_docs_image.png
Normal file
BIN
images/websurfx_docs_image.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 5.4 KiB |
Loading…
Reference in New Issue
Block a user