alamin/websurfx
alamin/websurfx
0
0
Fork 0
mirror of https://github.com/neon-mmd/websurfx.git synced 2024-11-22 05:58:21 -05:00
Code Issues Releases Activity

docs: move docs from wiki to docs folder & add an image for docs

Browse Source
This commit is contained in:
neon_arch 2023-05-24 11:25:25 +03:00
parent 3c313543f3
commit 0d271a0fcf
7 changed files with 496 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
docs/README.md Normal file
View 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
View 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
View 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
View 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
View 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
View 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
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.4 KiB