{"id":14156544,"url":"https://github.com/NebulaServices/Nebula","last_synced_at":"2025-08-06T02:33:50.562Z","repository":{"id":39162371,"uuid":"490067503","full_name":"NebulaServices/Nebula","owner":"NebulaServices","description":"a stunning and sleek web proxy with support for hundreds of popular sites. ","archived":false,"fork":false,"pushed_at":"2024-12-02T15:02:33.000Z","size":25373,"stargazers_count":285,"open_issues_count":3,"forks_count":3917,"subscribers_count":19,"default_branch":"main","last_synced_at":"2024-12-02T16:25:14.215Z","etag":null,"topics":["cloudflare","proxy","unblocker","webdevelopment","webproxy"],"latest_commit_sha":null,"homepage":"https://docs.nebulaproxy.io/","language":"Astro","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NebulaServices.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"patreon":"nebuladevs","ko_fi":"nebulaa"}},"created_at":"2022-05-08T22:17:54.000Z","updated_at":"2024-12-02T15:02:59.000Z","dependencies_parsed_at":"2023-12-25T03:19:31.173Z","dependency_job_id":"365b72ea-771d-479b-bd65-7feb2dd7aab8","html_url":"https://github.com/NebulaServices/Nebula","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NebulaServices%2FNebula","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NebulaServices%2FNebula/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NebulaServices%2FNebula/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NebulaServices%2FNebula/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NebulaServices","download_url":"https://codeload.github.com/NebulaServices/Nebula/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228829201,"owners_count":17978166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare","proxy","unblocker","webdevelopment","webproxy"],"created_at":"2024-08-17T08:06:12.561Z","updated_at":"2025-08-06T02:33:50.549Z","avatar_url":"https://github.com/NebulaServices.png","language":"Astro","readme":"\u003cdiv align=\"center\"\u003e\n         \n\u003cimg src=\"https://socialify.git.ci/nebulaservices/nebula/image?description=1\u0026font=Inter\u0026forks=1\u0026issues=1\u0026language=1\u0026name=1\u0026owner=1\u0026pattern=Circuit%20Board\u0026pulls=1\u0026stargazers=1\u0026theme=Dark\" alt=\"ruby\" width=\"640\" height=\"320\" /\u003e\n\n\u003cimg alt=\"repo size\" src=\"https://img.shields.io/github/repo-size/nebulaservices/nebula?style=for-the-badge\"\u003e\u003c/img\u003e\n\u003cimg alt=\"website status\" src=\"https://img.shields.io/website?url=https%3A%2F%2Fnebulaproxy.io\u0026style=for-the-badge\"\u003e\u003c/img\u003e\n\u003cimg alt=\"commit a week\" src=\"https://img.shields.io/github/commit-activity/w/nebulaservices/nebula?style=for-the-badge\"\u003e\u003c/img\u003e\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n    \u003ch2\u003eGet Started\u003c/h2\u003e\n    \u003ca\u003eTo get started, press one of the buttons below to deploy Nebula\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"#terminal\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/terminal-%23121011.svg?style=for-the-badge\u0026logo=gnu-bash\u0026logoColor=white\" alt=\"Terminal\"\u003e\n        \u003c/img\u003e\n    \u003c/a\u003e\n    \u003ca href=\"#docker\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge\u0026logo=docker\u0026logoColor=white\" alt=\"Docker\"\u003e\n        \u003c/img\u003e\n    \u003c/a\u003e\n\u003c/div\u003e\n\n## NOTE:\n\n-   This will **NOT** deploy on GitHub Pages, Netlify, Vercel, Gitlab Pages, or any other _static_ host\n-   This will **NOT** work on Render\n---\n\n## How to get links\n\n[![Nebula Services Discord](https://invidget.switchblade.xyz/unblocker?theme=darl)](https://discord.gg/unblocker)\n[![Titanium Network Discord](https://invidget.switchblade.xyz/unblock?theme=dark)](https://discord.gg/unblock)\n\n---\n\n## Contact\n\n-   You can E-Mail us at:\n    -   Legal concerns: legal@nebulaservices.org\n    -   Contact: contact@nebulaservices.org\n---\n\n## Features\n\n-   Multiple Proxy \"Backends\":\n    -   [Ultraviolet](https://github.com/titaniumnetwork-dev/ultraviolet)\n    -   [Scramjet](https://github.com/mercuryworkshop/scramjet)\n---\n\n## Contributors\n\n- [Rifting](https://github.com/rifting) - Owner \u0026 Maintainer\n- [MotorTruck1221](https://motortruck1221.com) - Maintainer\n---\n\n## Tech Stack\n\n-   [Astro](https://astro.build)\n-   [Tailwind](https://tailwindcss.com/)\n-   [Svelte](https://svelte.dev/)\n-   [Fastify](https://fastify.dev)\n-   [Ultraviolet](https://github.com/titaniumnetwork-dev/ultraviolet)\n-   [Scramjet](https://github.com/mercuryworkshop/scramjet)\n-   [Epoxy](https://github.com/mercuryworkshop/epoxy-tls)\n-   [Libcurl.js](https://github.com/ading2210/libcurl.js)\n---\n\n## Catalog/Marketplace\n\n- By default, the marketplace is enabled and uses SQLite\n    - If you encounter any issues with SQLite3, please run the `fix_sqlite3.sh` script\n- If you would like to disable the catalog, see [#config](#config)\n- For big production instances, I recommend using PostgreSQL rather than SQLite. To do this see [#config](#config)\n- To use PostgreSQL via the provided docker-compose files, see [#docker](#docker)\n\n### How to make a theme\n\n- Themes allow you to customize Nebula's *look*.\n\n#### Prerequisites:\n  - Make sure you have our [Discord server](https://discord.gg/unblocker) so you can submit your theme\n\n##### Making the themes:\n\n1. Firstly, copy the CSS vars:\n```css\n:root {\n    --background-primary: /*Your stuff here */;\n    --background-lighter: ;\n    --navbar-color: ;\n    --navbar-text-color: ;\n    --navbar-link-color: ; \n    --navbar-link-hover-color: ; \n    --input-text-color: ;\n    --input-placeholder-color: ; \n    --input-background-color: ;\n    --input-border-color: ;\n    --tab-color: ;\n    --border-color: ; \n}\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e You can add a custom font as well! To do so, add this to your `:root`\n\u003e \n\u003e ```css\n\u003e --font-family: /* Font family name */;\n\u003e ```\n\u003e \n\u003e And this to the bottom of your CSS file/submission:\n\u003e ```css\n\u003e @font-face {\n\u003e    font-family: /* Name */;\n\u003e    src: url(/* Where the font is located! Local or external work! */);\n\u003e   }\n\u003e  ```\n\u003e\n\u003e A good example of using a custom font is the built-in `retro` theme [here](./database_assets/com.nebula.retro)\n\n2. Add your colors and test! (Either with a self-hosted version of Nebula OR via a live preview (no clue when this will happen)\n\n3. Once you're satisfied with the colors, submit your theme to the [Discord Server](https://discord.gg/unblocker)!\n\n---\n### How to make a plugin\n\n- Plugins extend the functionality of either the proxied page(s) or the service worker.\n- This guide provides an incredibly basic example of how to make either.\n\n#### Prerequisites:\n  - Make sure you have joined our [Discord server](https://discord.gg/unblocker) so you can submit your plugin.\n  - Some knowledge of JS/TS\n\n##### Serviceworker plugin:\n\n- These plugins are handled by Workerware see [here](https://github.com/mercuryworkshop/workerware) for docs.\n\n1. Create an index.js (or other file name) file:\n```bash\ntouch index.js\n```\n\n2. Edit that file to include either of these:\n    - Code encased in a string:\n    ```js\n    function setup() {\n        // This function MUST return the following attributes:\n        return {\n            function: `console.log('Example code.')`,\n            name: 'com.example', // Technically, it could be named anything. It is recommended to use the same name for everything (name when submitting and this)        \n            events: ['fetch'] // See: https://github.com/mercuryworkshop/workerware for the event types you can use. (Also typed if you are using typescript)\n        }\n    }\n    \n    //This can be named anything. However, it's recommended to use `entryFunc` (with types, the naming IS enforced)\n    self.entryFunc = setup; //DO NOT call the function here. Only assign the reference otherwise, it will error.\n    ```\n    - Code in an arrow function:    \n    ```js\n    const example = () =\u003e {\n        console.log('Example code')\n    }\n\n    function setup() {\n        //This function MUST return the following attributes:\n        return {\n            function: example, //Do not call the function, only assign the reference to the function.\n            name: 'com.example', // Technicall could be name anything. Recommended to use the same name for everything (name when submitting and this)\n            event: ['fetch'] // Se https://github.com/mercuryworkshop/workerware for the event types you can use. (Also typed if using typescript)\n        }\n    }\n\n    //This can be named anything. However, it's recommended to use `entryFunc` (with types, the naming IS enforced)\n    self.entryFunc = setup; //DO NOT call the function here. Only assign the reference; otherwise, it will result in an error.\n    ```\n\n\u003e [!WARNING]\n\u003e The only *allowed* way to pass code to the `function` param is either a string or an arrow function. Named functions ***WILL NOT WORK***.\n\u003e\n\u003e Example of a named function: `function example() {/* Some form of code */}`.\n\u003e\n\u003e If a named function is used where it shouldn't be, your plugin will not be approved, nor will it work properly.\n\n3. Submit your plugin in the [Discord](https://discord.gg/unblocker)!\n\n##### Proxied page plugins\n\n- They allow modification of websites that UV proxies, (EX: you could add Vencord to Discord with this)\n\n1. Create an index.js file (or another file name)\n```bash\ntouch index.js\n```\n\n2. Edit that file with your code and the following:\n```js\n//Name this whatever.\nfunction example() {\n    //You MUST return the following\n    return {\n        host: \"example.com\", //The host to match (so if the user visits example.com it will inject the html below.\n        html: \"\u003cscript\u003econsole.log('Example')\u003c/script\u003e\", //Must return a string (and be valid HTML or your plugin will break). How you get that string is up to you\n        injectTo: \"head\" // Can be \"head\" or \"body\"\n    }\n}\n\n// Technically, this could be named anything, it is recommended to call it `entryFunc`\nself.entryFunc = example; //DO NOT run the function here. That will cause errors. Only assign the reference to the function here.\n```\n\n3. Submit it in our [Discord](https://discord.gg/unblocker)!\n\n---\n\n## Deployment\n\n### Terminal\n\nPrerequisites:\n- Node \u0026 npm (pnpm recommended!)\n- Git\n\n0. Install pnpm\n```bash\nnpm i -g pnpm\n```\n\n1. Clone the repo:\n```bash\ngit clone https://github.com/nebulaservices/nebula --recursive \u0026\u0026 cd nebula\n```\n\n2. Install all of the dependencies:\n```bash\npnpm i\n```\n\n3. Create a `config.toml` file\n```bash\ncp config.example.toml config.toml\n```\n\n4. Modify the `config.toml` file to your liking (docs [here](#environment))\n```\nnano config.toml\n```\n\n5. Build the front end \u0026 server:\n```bash\npnpm build\n```\n\n6. Start the server\n```bash\npnpm start\n```\n\n\u003e [!NOTE]\n\u003e You can run `pnpm bstart` to build and start together\n---\n\n### Docker\n**CURRENTLY DOCKER DOES NOT WORK!! For some reason the docker image doesn't exist in Dockhub**\n- There are two ways to deploy with docker:\n    - [Normal docker](#normal-docker)\n    - [Docker Compose](#docker-compose)\n\n#### Normal Docker\n\nPrerequisites:\n- Git\n- Docker\n\n1. Clone the repo (skip if using a prebuilt image):\n```bash\ngit clone https://github.com/nebulaservices/nebula --recursive \u0026\u0026 cd nebula\n```\n\n2. Create an `config.toml` file (if using prebuilt image, copy the example from the repo):\n```bash\ncp config.example.toml config.toml\n```\n\n3. Modify the `config.toml` file to your liking (docs [here](#environment))\n```bash\nnano config.toml\n```\n\n4. Build the docker image (skip if using prebuilt):\n```bash\ndocker build nebula:latest\n```\n5. Run the docker images:\n\n    - Prebuilt:\n    ```bash\n    docker run -v ./config.toml:/app/config.toml ghcr.io/nebulaservices/nebula:latest\n    ```\n    - Image you built yourself:\n    ```bash\n    docker run -v ./config.toml:/app/config.toml nebula:latest\n    ```\n\n#### Docker Compose\n\nPrerequisites:\n- Git\n- Docker w/compose\n\n1. Clone the repo (skip if using a prebuilt image):\n```bash\ngit clone https://github.com/nebulaservices/nebula --recursive\n```\n\n2. Create an `config.toml` file (if using prebuilt image, copy the example from the repo):\n```bash\ncp config.example.toml config.toml\n```\n\n3. Modify the `config.toml` file to your liking (docs on that [here](#environment)]\n```bash\nnano config.toml\n```\n\n4. Build the docker image (skip if using prebuilt):\n```bash\ndocker compose -f ./docker-compose.build.yml build\n```\n\n5. Run the docker image:\n\n    - Prebuilt:\n    ```bash\n    docker compose up\n    ```\n    - Image you built yourself:\n    ```bash\n    docker compose -f ./docker-compose.build.yml up\n    ```\n#### Extra (Postgres)\n\n- 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](#config) for knowledge on how to do this)\n- 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](#config) for knowledge on how to do this)\n\n---\n\n## Config\n\nThere 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.\n- An example config file is located [here](./config.example.toml). \n- Config format is in TOML\n\n| Variable | Description | Type | Default |\n|:----------:|:-------------:|:------:|:---------:|\n| `marketplace` | The options below are for the marketplace section | `object` | N/A |\n| `enabled` | Enable marketplace functionality | `boolean` | `true` |\n| `psk` | The password and authentication key for the marketplace. ***CHANGE FROM DEFAULT*** | `string` | `CHANGEME` |\n|----------------------------| ----------------------------------------------------------------------------|------------|--------------|\n| `db` | The below options are for the db (database) section | `object` | N/A |\n| `name` | The database name to use | `string` | `database` |\n| `username` | The username for the DB | `string` | `username` |\n| `password` | The database password. ***CHANGE FROM DEFAULT VALUE*** | `string` | `password` |\n| `postgres` | Whether to use postgres over sqlite *(recommended for large production instances)* | `boolean` | `false` |\n|----------------------------| ----------------------------------------------------------------------------|------------|--------------|\n| `postgres` | The below options are for the postgres section. (Only worry about this if you enabled postgres in the db section.) | `object` | N/A |\n| `domain` | Either the TLD or the IP address of your postgres server. | `string` | `''` |\n| `port` | The port your postgres server is listening on | `number` | `5432` |\n|----------------------------| ----------------------------------------------------------------------------|------------|--------------|\n| `server.server` | The below options are to configure the server. | `object` | N/A |\n| `port` | What port the server should listen on. *(Note: Can also be configured via environment variable `PORT`)* | `number` | `8080` |\n| `wisp` | Whether the server should use the inbuilt wisp server. (Disabled if your using an external wisp server) | `boolean` | `true` |\n| `logging` | Whether or not to enable logging. *Note: Logs are massive* | `boolean` | `true` |\n|----------------------------| ----------------------------------------------------------------------------|------------|--------------|\n| `masqr` | The below options are to configure masqr. | `object` | N/A |\n| `enabled` | Enable masqr | `boolean` | `false` |\n| `failed` | Default masqr failed page (For using per-site failed pages, create a create a DOMAIN.html file (Ex. www.example.com.html) inside the root project directory| `string` | `failed.html` |\n| `whitelisted` | List of domains to skip masqr| `object` | `[\"\"]` |\n| `url` | URL for validating masqr licenses | `string` | `` |\n|----------------------------| ----------------------------------------------------------------------------|------------|--------------|\n\n## Deploying\n### Koyeb\n- First setup the config.toml file with the docker-compose instructions!\n- Fork this repo\n- Create new koyeb service, and select webservice\n- Select import from github and import your forked repo\n- Change package to dockerfile and press deploy!\n","funding_links":["https://patreon.com/nebuladevs","https://ko-fi.com/nebulaa"],"categories":["webdevelopment"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNebulaServices%2FNebula","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNebulaServices%2FNebula","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNebulaServices%2FNebula/lists"}