Nebula

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:

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

Add your colors and test! (Either with a self-hosted version of Nebula OR via a live preview (no clue when this will happen)
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.

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

touch index.js

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.

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)

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

touch index.js

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.

Submit it in our Discord!

Deployment

Terminal

Prerequisites:

Node & npm
Git

Clone the repo:

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

Install all of the dependencies:

npm i

Create a config.toml file

cp config.example.toml config.toml

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

nano config.toml

Build the front end & server:

npm run build

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

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

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

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

cp config.example.toml config.toml

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

nano config.toml

Build the docker image (skip if using prebuilt):

docker build nebula:latest

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

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

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

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

cp config.example.toml config.toml

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

nano config.toml

Build the docker image (skip if using prebuilt):

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

Run the docker image:
- Prebuilt:
Terminal window
```
docker compose up
```
- Image you built yourself:
Terminal window
```
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

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!