The Open-Source and Self-Hosted Alternative to Heroku, Netlify, and Vercel 🚀

<div> <a href="https://ko-fi.com/codewithrodi"> <img align="left" src="https://cdn.ko-fi.com/cdn/kofi3.png?v=3" height="50" width="180" alt="Support Quantum!" /></a> </div> <br /> <br />

Table of Contents

• Cloning Repository
• Deploying with Quantum Setup Utility (Recommended)
• Deploying with Docker Compose
• Quantum CLI via Docker
• In Case You Don’t Deploy in Docker
• Features
• Obtaining GitHub Client Secret and Client ID
• Using NGINX as a Reverse Proxy
• The Quantum CLI & Admin User Creation
• Where Are Repositories and Logs Stored?
• What Happens When the Server Is Closed?
• Custom Domains for Your Deployments
• How Can I Migrate to New Versions?
• We'd Love Your Feedback and Support!

Quantum allows you to effortlessly deploy your GitHub repositories, integrating real-time continuous deployment seamlessly. Additionally, you can easily deploy and manage Docker containers. With "One Click Services," you have access to over 20 applications that you can deploy to your Quantum account with just a single click. Among these applications are Uptime Kuma, Code Server, Ollama, various Databases, and many more.

With Quantum, you have full access to the file systems of all your Docker containers and your deployed GitHub repositories. This enables you to make adjustments directly without the need to perform an immediate commit. You can configure environment variables, access the terminal, restart or shut down containers, and utilize many other functionalities.

To deploy the application, you can use the Quantum Setup Utility, which simplifies the installation process on your VPS quickly and easily. Alternatively, you also have the option to use Docker Compose.

While Quantum offers a panel for configuring commands such as installing dependencies (e.g., "npm install"), building source code (e.g., "npm run build"), or starting your software (e.g., "npm run start"), it also provides a separate panel specifically for managing environment variables. It's worth noting that this isn't a manual process where you input variables and their values one by one. When the repository is cloned, Quantum automatically maps the environment variables, allowing you to assign their respective values later on. You have the flexibility to create, delete, and modify environment variables associated with the deployment of your repository as needed.

I've successfully migrated all my frontend applications from Vercel and my various VPS services to Quantum. The platform's ease of use and efficiency are evident in the 15 repositories I currently have deployed – a testament to my confidence in Quantum.

Cloning Repository

git clone https://github.com/rodyherrera/Quantum

This command clones the Quantum repository from GitHub to your local machine.

You can deploy using Quantum Setup Utility (Recommended), Docker Compose or from source.

Deploying with Quantum Setup Utility (Recommended)

The easiest way to deploy is with Docker. You can configure environment variables through the .env file located at the root of the repository. And then just type docker compose up -d --build. But also, you can use the Quantum deployment tool.

In the root of the repository write the following command:

bash scripts/deploy-setup-utility.sh

Once executed, the deployment of the tool should begin, environment variables will be adjusted automatically and this is the reason why we recommend using this method.

NOTE: If you want to use a domain, you can use NGINX to reverse proxy or use the NGINX Reverse Proxy application (Recommended).

Deploying with Docker Compose

Deploying through Docker is relatively simple. Within the root of the directory there is a .env file. You must fill in ALL the variables that are NOT commented. Those environment variables that are mentioned are optional.

Then, run the following command in the root of the directory.

docker-compose up -d --build 

When deploying to Docker, you will have three new containers:

1. The Quantum server (back-end)
2. The web application (front-end)
3. The MongoDB instance (database)

By default, the back-end server will be deployed on port 7080. The front-end server on port 5050.

NOTE: If you want to use a domain, you can use NGINX to reverse proxy or use the NGINX Reverse Proxy application (Recommended).

Quantum CLI via Docker

This is useful, as it will help you create your administrator user. If you have already deployed to Docker, you can access the CLI via the following command:

docker exec -it quantum-server-1 npm run cli

After running it, if your container is active, you will be able to correctly access the available options. You can learn more about the Quantum CLI here.

In case you don't deploy in Docker

Thought about Docker and deployment setup for 5 seconds Here’s a unified text that summarizes everything clearly:

When deploying with Docker, you only need to edit a single .env file located at the root of the repository (as mentioned in the corresponding section). Most environment variables are already set, so you typically only have to adjust the secret keys.

If you choose not to use Docker, you must still configure the environment variables, but this time they won’t be centralized in a single file. Instead, you’ll need to modify variables in both the client/ and server/ directories, and you’ll also have to update additional variables—such as the MongoDB URI.

For the client application, go to the client/ directory, run npm install, then npm run build. After building, you can serve the dist folder on a specific port with a tool like serve by running npx serve -s dist. In that same folder, rename client/.env.example to client/.env. There are only two variables you need to change:

# VITE_SERVER: Address where the 
# Quantum backend is deployed.
VITE_SERVER = http://0.0.0.0:8000

# VITE_API_SUFFIX: Suffix to make API 
# calls, you should not change /api/v1.
VITE_API_SUFFIX = /api/v1

For the server application, navigate to the server/ directory, run npm install, and then launch the server with npm run start.

Once you’ve configured and built both the client and server applications (and updated all necessary environment variables), you’ll have everything you need to proceed with the deployment.

Obtaining GitHub Client Secret and Client ID

To integrate your application with GitHub's API, you'll need to obtain a Client Secret and Client ID. Follow these detailed steps to acquire them:

1. Sign in to your GitHub account: Go to GitHub and sign in with your user credentials.
2. Access your account settings: Click on your profile avatar in the top right corner and select "Settings" from the dropdown menu.
3. Navigate to the "Developer settings" section: In the left sidebar, click on "Developer settings."
4. Create a new OAuth application: Select "OAuth Apps" and click on the "New OAuth App" button.
5. Provide application information: Please enter your app name, your home page URL, and return authorization URL. Please note that the "Home Page URL" must be the address where the server is hosted and cannot be local, that is, it must be accessible to third parties, for example: "http://82.208.22.71:5001 " or "quantum-server.mydomain.com". Likewise, the "Return Authorization URL" must contain the address where the server is hosted followed by the path of the API responsible for returning authorization from Github, for example: "http://82.208.22.71:5002/api/v1/github/callback/" or "https://quantum-server.mydomain.com/api/v1/github/callback/".
6. Register the application: Click on the "Register application" button.
7. Copy the application credentials: Once registered, GitHub will generate a Client ID and Client Secret. Copy these values and securely store them.
8. Utilize the credentials in your application: Use the Client ID and Client Secret in your application's configuration to authenticate requests to GitHub's API.

It is important that you do this step, otherwise NO ONE will simply be able to use your application, including you.

Using NGINX as a reverse proxy

If you want to assign a custom domain (or multiple domains) to your Quantum deployment, using NGINX as a reverse proxy is the recommended approach. Below is a general outline of how to set this