NOTE:

• This will NOT deploy on GitHub Pages, Netlify, Vercel, Gitlab Pages, or any other static host
• This will NOT work on Render

---

How to get links

---

Contact

• You can E-Mail us at:
  • Legal concerns: legal@nebulaservices.org
  • Contact: contact@nebulaservices.org

---

Features

• Multiple Proxy "Backends":
  • Ultraviolet
  • Scramjet

---

Contributors

• Rifting - Owner & Maintainer
• MotorTruck1221 - Maintainer
• Scaratek - Maintainer
• Skylink - Providing hosting

---

Tech Stack

• Astro
• Tailwind
• Svelte
• Fastify
• Ultraviolet
• Scramjet
• Epoxy
• Libcurl.js

---

Catalog/Marketplace

• By default, the marketplace is enabled and uses SQLite
  • If you encounter any issues with SQLite3, please run the fix_sqlite3.sh script
• If you would like to disable the catalog, see #config
• For big production instances, I recommend using PostgreSQL rather than SQLite. To do this see #config
• To use PostgreSQL via the provided docker-compose files, see #docker

How to make a theme

• Themes allow you to customize Nebula's look.

Prerequisites:

• Make sure you have our Discord server so you can submit your theme

Making the themes:

1. Firstly, copy the CSS vars:

:root {
    --background-primary: /*Your stuff here */;
    --background-lighter: ;
    --navbar-color: ;
    --navbar-text-color: ;
    --navbar-link-color: ; 
    --navbar-link-hover-color: ; 
    --input-text-color: ;
    --input-placeholder-color: ; 
    --input-background-color: ;
    --input-border-color: ;
    --tab-color: ;
    --border-color: ; 
}

[!NOTE]

You can add a custom font as well! To do so, add this to your :root

--font-family: /* Font family name */;

And this to the bottom of your CSS file/submission:

@font-face {
   font-family: /* Name */;
   src: url(/* Where the font is located! Local or external work! */);
  }

A good example of using a custom font is the built-in retro theme here

2. Add your colors and test! (Either with a self-hosted version of Nebula OR via a live preview (no clue when this will happen)

3. Once you're satisfied with the colors, submit your theme to the Discord Server!

---

How to make a plugin

• Plugins extend the functionality of either the proxied page(s) or the service worker.
• This guide provides an incredibly basic example of how to make either.

Prerequisites:

• Make sure you have joined our Discord server so you can submit your plugin.
• Some knowledge of JS/TS

Serviceworker plugin:

• These plugins are handled by Workerware see here for docs.

1. Create an index.js (or other file name) file:

touch index.js

2. Edit that file to include either of these:
   • Code encased in a string:

   function setup() {
       // This function MUST return the following attributes:
       return {
           function: `console.log('Example code.')`,
           name: 'com.example', // Technically, it could be named anything. It is recommended to use the same name for everything (name when submitting and this)        
           events: ['fetch'] // See: https://github.com/mercuryworkshop/workerware for the event types you can use. (Also typed if you are using typescript)
       }
   }
   
   //This can be named anything. However, it's recommended to use `entryFunc` (with types, the naming IS enforced)
   self.entryFunc = setup; //DO NOT call the function here. Only assign the reference otherwise, it will error.
   

   • Code in an arrow function:

   const example = () => {
       console.log('Example code')
   }
   
   function setup() {
       //This function MUST return the following attributes:
       return {
           function: example, //Do not call the function, only assign the reference to the function.
           name: 'com.example', // Technicall could be name anything. Recommended to use the same name for everything (name when submitting and this)
           event: ['fetch'] // Se https://github.com/mercuryworkshop/workerware for the event types you can use. (Also typed if using typescript)
       }
   }
   
   //This can be named anything. However, it's recommended to use `entryFunc` (with types, the naming IS enforced)
   self.entryFunc = setup; //DO NOT call the function here. Only assign the reference; otherwise, it will result in an error.
   

[!WARNING] The only allowed way to pass code to the function param is either a string or an arrow function. Named functions WILL NOT WORK.

Example of a named function: function example() {/* Some form of code */}.

If a named function is used where it shouldn't be, your plugin will not be approved, nor will it work properly.

3. Submit your plugin in the Discord!

Proxied page plugins

• They allow modification of websites that UV proxies, (EX: you could add Vencord to Discord with this)

1. Create an index.js file (or another file name)

touch index.js

2. Edit that file with your code and the following:

//Name this whatever.
function example() {
    //You MUST return the following
    return {
        host: "example.com", //The host to match (so if the user visits example.com it will inject the html below.
        html: "<script>console.log('Example')</script>", //Must return a string (and be valid HTML or your plugin will break). How you get that string is up to you
        injectTo: "head" // Can be "head" or "body"
    }
}

// Technically, this could be named anything, it is recommended to call it `entryFunc`
self.entryFunc = example; //DO NOT run the function here. That will cause errors. Only assign the reference to the function here.

3. Submit it in our Discord!

---

Deployment

Terminal

Prerequisites:

• Node & npm (pnpm recommended!)
• Git

0. Install pnpm

npm i -g pnpm

1. Clone the repo:

git clone https://github.com/nebulaservices/nebula --recursive && cd nebula

2. Install all of the dependencies:

pnpm i

3. Create a config.toml file

cp config.example.toml config.toml

4. Modify the config.toml file to your liking (docs here)

nano config.toml

5. Build the front end & server:

pnpm build

6. Start the server

pnpm start

[!NOTE] You can run pnpm bstart to build and start together

---

Docker

CURRENTLY DOCKER DOES NOT WORK!! For some reason the docker image doesn't exist in Dockhub

• There are two ways to deploy with docker:
  • Normal docker
  • Docker Compose

Normal Docker

Prerequisites:

• Git
• Docker

1. Clone the repo (skip if using a prebuilt image):

git clone https://github.com/nebulaservices/nebula --recursive && cd nebula

2. Create an config.toml file (if using prebuilt image, copy the example from the repo):

cp config.example.toml config.toml

3. Modify the config.toml file to your liking (docs here)

nano config.toml

4. Build the docker image (skip if using prebuilt):

docker build nebula:latest

5. Run the docker images:

   • Prebuilt:

   docker run -v ./config.toml:/app/config.toml ghcr.io/nebulaservices/nebula:latest
   

   • Image you built yourself:

   docker run -v ./config.toml:/app/config.toml nebula:latest
   

Docker Compose

Prerequisites:

• Git
• Docker w/compose

1. Clone the repo (skip if using a prebuilt image):

git clone https://github.com/nebulaservices/nebula --recursive

2. Create an config.toml file (if using prebuilt image, copy the example from the repo):

cp config.example.toml config.toml

3. Modify the config.toml file to your liking (docs on that here]

nano config.toml

4. Build the docker image (skip if using prebuilt):

docker compose -f ./docker-compose.build.yml build

5. Run the docker image:

   • Prebuilt:

   docker compose up
   

   • Image you built yourself:

   docker compose -f ./docker-compose.build.yml up
   

Extra (Postgres)

• To use Postgres over SQLite, uncomment the DB section in the docker-compose file (or use your own Postgres DB!). Then, modify the config.toml (See: #config for knowledge on how to do this)
• To use Postgres over SQLite in a normal docker environment (no compose), you'll have to set one up and then modify the config.toml to use it. (See: #config for knowledge on how to do this)

---

Config

There are a couple of configuration options for Nebula. The defaults are fine most of the time, but there are instances where you may not want certain options enabled or certain things running.

• An example config file is located here.
• Config format is in TOML

Deploying

Koyeb

• First setup the config.toml file with the docker-compose instructions!
• Fork this repo
• Create new koyeb service, and select webservice
• Select import from github and import your forked repo
• Change package to dockerfile and press deploy!