Get Started

To get started, press one of the buttons below to deploy Nebula

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

---

Features

• Multiple Proxy "Backends":
  • Ultraviolet
  • RammerHead

---

Contributors

• Rifting - Owner & Maintainer
• MotorTruck1221 - Maintainer

---

Tech Stack

• Astro
• Fastify
• Ultraviolet
• RammerHead
• Epoxy
• Libcurl.js
• HTML, CSS, and JavaScript (DUH)

---

Catalog/Marketplace

• By default, the marketplace is enabled and uses SQLite
• 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
• Git

1. Clone the repo:

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

2. Install all of the dependencies:

npm 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:

npm run build

6. Start the server

npm start

Note

You can run npm run bstart to build and start together

---

Docker

• 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

Variable	Description	Type	Default
marketplace	The options below are for the marketplace section	object	N/A
enabled	Enable marketplace functionality	boolean	true
psk	The password and authentication key for the marketplace. CHANGE FROM DEFAULT	string	CHANGEME
----------------------------	----------------------------------------------------------------------------	------------	--------------
db	The below options are for the db (database) section	object	N/A
name	The database name to use	string	database
username	The username for the DB	string	username
password	The database password. CHANGE FROM DEFAULT VALUE	string	password
postgres	Whether to use postgres over sqlite (recommended for large production instances)	boolean	false
----------------------------	----------------------------------------------------------------------------	------------	--------------
postgres	The below options are for the postgres section. (Only worry about this if you enabled postgres in the db section.)	object	N/A
domain	Either the TLD or the IP address of your postgres server.	string	''
port	The port your postgres server is listening on	number	5432
----------------------------	----------------------------------------------------------------------------	------------	--------------
server.server	The below options are to configure the server.	object	N/A
port	What port the server should listen on. (Note: Can also be configured via environment variable PORT)	number	8080
wisp	Whether the server should use the inbuilt wisp server. (Disabled if your using an external wisp server)	boolean	true
logging	Whether or not to enable logging. Note: Logs are massive	boolean	true
----------------------------	----------------------------------------------------------------------------	------------	--------------

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!