hellgate/readme.md

![hellgate logo](mandatory-js-project-logo.png)
----
An extensible, general purpose http-\>gemini mirror with full
javascript support

## Requirements - If you are using Docker
- docker

## Requirements - If you are not using Docker
- nodejs
- npm
- electron
- openssh
- sh
- libgtk-2-0
- libgconf-2-4
- libxshmfence1
- libnss3
- libatk-bridge2.0-0
- libdrm2
- libgtk-3-0
- libgbm
- libasound2
- xvfb (if you're running it headless)

## Setup - If you are using Docker
- `docker pull sose/hellgate`
- `docker run -p 1965:1965 sose/hellgate`
- the server will listen on `localhost:1965`
- If you are using port 1965 on the host machine, you can bind a different port
  by running `docker run -p {PORT}:1965 sose/hellgate` instead

## Setup - If you are not using Docker
- `sudo apt install npm nodejs libgtk2.0-0 libgconf-2-4 libxshmfence1 libnss3
  libatk-bridge2.0-0 libdrm2 libgtk-3-0 libgbm1 libasound2` (if you're on
debian, other
  distros idk)
- `sudo apt install xvfb` (again, on debian)
- `git clone https://tildegit.org/sose/hellgate`
- `cd hellgate`
- `sudo npm install -g electron --unsafe-perm=true`
- `npm install`
- `./gen_cert`
- `npm start` or `xvfb-run npm start`
    - The server will listen on `[::1]:1965` by default

## Using
- Supply a full url in the query string in a request to the server and it will be rendered in Gemtext
- ex. `gemini://localhost?https://tilde.town`
- You have to include the scheme or Hellgate will not recognize it

## Sigils
- By default, more complex sites that are rendered by hellgate are not very
  pretty, and sometimes downright unreadable
- For this, users can create website specific 'sigils' to display content in a
  certain way, or to automate certain actions on a website
- Sigils are located in the `sigils` dir and are titled with the domain name of
  their corresponding website
- See [writing sigils](writing_sigils.md) for more info on how to write sigils
  and how they work
- If you write a new sigil for a specific website, don't hesitate to send it as
  a pull request to this repo

## Security
- Obviously, executing arbitrary Javascript from around the web is never going
  to be completely safe, however the following steps have been taken to ensure
    the saftey of the host machine:
    - All websites have a maximum time in which they have to load their
          content (default 2s) and execute any scripts (default 2s)
    - When running outside of a Docker container, all renderer processes
          will be run inside the Chromium sandbox
(https://github.com/chromium/chromium/blob/master/docs/linux/sandboxing.md)
    - When running inside of a Docker container, the entire program is
          running inside a Docker container (as an unprivileged user).
    - Nodejs integration is disabled in all renderer processes
    - Context isolation is enabled in all reneder processes
    - Any request for browser permissions is automatically denied
    - Any request to create a new window is automatically denied
- Essentially, in theory, the machine hosting hellgate should not be at any
  more risk than a regular web broser. However, security vulnerabilities
exists, and no software is perfect, not Docker, not Chromium, not Linux not
Electron and *certainly* not Hellgate. If you have valuable things on your
server I would suggest running all of this in a VM, just in case.

## Other Notes
- This isn't a proxy meant to be run on the user's machine, rather many users 
are meant to connect to a single hosted version, such as 
gemini://illegaldrugs.net/cgi-bin/hellgate. I would never want you to install 
npm on your machine :)
- As of right now the npm version of gemini-server is broken, use the version
  from github or this will not work.
- If you are using the docker container this is already done for you.