diff --git a/README.md b/README.md index feee03a..91781d4 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,81 @@ -# Ultraviolet -Ultraviolet application +# Ultraviolet-Node +The deployable version of Ultraviolet. -[![Deploy to Heroku](https://raw.githubusercontent.com/BinBashBanana/deploy-buttons/master/buttons/remade/heroku.svg)](https://heroku.com/deploy/?template=https://github.com/titaniumnetwork-dev/uv-app) -[![Run on Replit](https://raw.githubusercontent.com/BinBashBanana/deploy-buttons/master/buttons/remade/replit.svg)](https://replit.com/github/titaniumnetwork-dev/uv-app) +[![Deploy to Heroku](https://raw.githubusercontent.com/BinBashBanana/deploy-buttons/master/buttons/remade/heroku.svg)](https://heroku.com/deploy/?template=https://github.com/titaniumnetwork-dev/Ultraviolet-Node) +[![Run on Replit](https://raw.githubusercontent.com/BinBashBanana/deploy-buttons/master/buttons/remade/replit.svg)](https://replit.com/github/titaniumnetwork-dev/Ultraviolet-Node) -# Steps -Installing on machine +## Table of Contents +- [Installation And Setup](#installation-and-setup) + - [Basic Guide](#basic-guide) + - [Replit Setup Guide](#replit-setup-guide) + - [Comprehensive Guide](#comprehensive-guide) + - [Configuration](#configuration) + - [Frontend](#static-files) + - [Core Scripts](#core-scripts) -``` -git clone https://github.com/titaniumnetwork-dev/ultraviolet-node/ -cd ultraviolet-node -git submodule update --init -npm install -npm install tomphttp/bare-server-node -npm start -``` -On Repl, make sure to run the `git submodule update --init` command in shell. +# Installation and Setup -`http://localhost:8080/` +Installation of Ultraviolet is simple. You can find a Tl;Dr of the installation and setup process just below. If you are unfamiliar with the "standard" installation process, look a bit farther down for a more comprehensive installation and setup guide. -Change server address properties when desired. +## Basic Guide -# Updating Bare -``` -git submodule update --remote +```sh +$ git clone --recursive https://github.com/titaniumnetwork-dev/Ultraviolet-Node +$ cd Ultraviolet-Node +$ npm install +$ npm start ``` -However, this may override files in `static/` so be careful. +## Replit Setup Guide + +To setup on Replit, first click on the "Run on Replit" button. After loading into your repl, run the following commands: +```sh +$ npm install +$ chmod +x main.sh +$ ./main.sh +``` + +You will only have to run the second command once. It just allows `main.sh` to be executed. By running `main.sh`, you will update any submodules and will start the app. + +**Note**: If you choose not to use `main.sh`, but would rather just run all commands manually, please note that you will have to manually install submodules by running `git update submodules --init`. Without it, `static` will not be installed, and that is a required directory. + +## Comprehensive Guide + +Below will describe a comprehensive guide to install Ultraviolet on Linux machines. + +To clone the repository, simply run the following command: + +```sh +$ git clone https://github.com/titaniumnetwork-dev/Ultraviolet-Node --recursive +``` + +The `--recursive` flag will clone the repository and all submodules. + +To begin work on the actual setup, cd into the repository. You can do so by running the following command: + +```sh +$ cd Ultraviolet-Node +``` + +From here, you can update your submodules and install your dependencies. To do so, run the following command: + +```sh +$ npm install +``` + +Finally, to start Ultraviolet, run the following command: + +```sh +$ npm start +``` + +You can then find Ultraviolet on `http://127.0.0.1:8080`. If you would like to change the port UV will be running on, edit the last line in `index.mjs`. + +Please note that UV will not function without HTTPS. If you are hosting on Replit or Heroku, this won't be a problem as they provide you with SSL/TLS by default and will automatically apply it to your instance, however if you are attempting to host UV on a different platform, such as a personal server, you **WILL** need to use HTTPS. + +## Configuration +Configuring Ultraviolet is very simple. Simple descriptions of each configurable option are provided as a comment in the block below. More detailed documentation can be found just below mentioned block. -# Ultraviolet Config `uv.config.js` ```javascript @@ -43,3 +90,22 @@ self.__uv$config = { sw: '/uv.sw.js', // Service Worker Script }; ``` + +| Configuration | Options and Explanation | +| ------------- | ----------------------- | +| Prefix | The prefix is the prefix that you want users to see. Ex: `https://example.com/service.` The default prefix is `service`. | +| Bare | Bare Servers can run on directories. For example, if the directory was /bare/ then the bare origin would look like `http://example.org/bare/`. The bare origin is passed to clients. | +| encodeUrl| EncodeUrl is how you want the URL a proxy site's visitors has to be encoded. Options include `Ultraviolet.codec.base64.encode`, `Ultraviolet.codec.plain.encode`, or `Ultraviolet.codec.xor.encode`. It is recommended that you use `xor` or `base64` as it hides the queries your visitors are searching and visiting. +| decodeURL | DecodeUrl is how you want the url to be decoded. It is recommended you keep it the same as `encodeUrl`. | +| Handler | Handler is the path to the UV handler. The default name and path to this file is `static/uv/uv.handler.js`. | +| Bundle | Bundle is the path to the UV bundle file. The default name and path to this file is `static/uv/uv.bundle.js`. | +| Config | Config is the path to the UV config file. The default name and path to this file is `static/uv/uv.bundle.js`. | +| SW | SW is the path to the UV Service Worker script. The default name and path to this file is `static/uv/uv.sw.js`. | + +## Static Files + +Static files is the frontend for Ultraviolet. A standalone repository for it can be found [here](https://github.com/titaniumnetwork-dev/Ultraviolet-Static). + +## Core Scripts + +[Configuration](#configuration) mentions a few scripts that make up Ultraviolet. To get documentation for what each of the scripts do, check out the [documentation](https://github.com/titaniumnetwork-dev/Ultraviolet-Core) for them in their standalone repository. \ No newline at end of file