Buffet

<div align="center" style="margin-bottom: 20px;"> <img src="assets/logo.png" alt="Buffet Logo" width="200" height="200"> </div> <div align="center"> <h1>Buffet</h1> <p>A full-stack, fully-featured web-based virtual machine manager</p>

</div>

Buffet is a full-stack, fully-featured web-based virtual machine manager that aims to provide a free, open-source, easy-to-use, secure alternative to other web-based virtual machine managers such as DistroSea and DistroTest.

The back-end is written in Python using the Flask web framework, and the front-end is written in TypeScript with the React library. Buffet uses QEMU and KVM for virtualization, and noVNC + websockify for remote desktop access.

Buffet in its original form was made over the course of 12 weeks as part of the final project for my bachelor's degree in Computer Systems at the School of Mathematical and Computer Sciences at Heriot-Watt University. Since then, I have continued to work on Buffet in my free time to improve it and add new features.

[!IMPORTANT] Please note that Buffet is not intended for production use, as it is still in the early stages of development.

However, you are welcome to use it for testing and development purposes. Please report any bugs or issues you encounter on the Issues page. Feel free to contribute to the project by submitting a pull request.

Features

• Access virtual machines securely using noVNC, websockify with SSL/TLS support, and randomly generated, one time VNC passwords
• Administer users, virtual machines and logs from the admin panel
• Create, start, and delete QEMU/KVM virtual machines
• Define custom operating systems and distributions using JSON
• Email-based account verification
• Fully responsive front-end that works on desktops, tablets, and smartphones
• Lightweight, easy-to-setup back-end using Flask and SQLAlchemy
• Runs on GNU/Linux servers with QEMU and KVM support
• Secure user authentication and authorisation using JSON Web Tokens (JWT), bcrypt and two-factor authentication
• Compatible with any relational database supported by SQLAlchemy, such as SQLite, PostgreSQL, MySQL, and MariaDB

Screenshots and GIFs

<div align="center"> <img src="assets/light-mode.png" alt="Light Mode"> <p>Buffet comes with a light theme that is easy on the eyes and looks great on any device.</p> </div> <div align="center"> <img src="assets/dark-mode.png" alt="Dark Mode"> <p>If you prefer a darker theme, Buffet has you covered with a dark mode that is easy on the eyes.</p> </div> <div align="center"> <img src="assets/virtual-machine-view.gif" alt="Virtual Machine View"> <p>The virtual machine view allows you to access your virtual machines using noVNC, and comes with draggable, usable navigation bars.</p> </div>

Installation

Buffet is designed to be easy to install and use. It consists of two main components: the front-end and the back-end. The front-end is a React application that communicates with the back-end using a RESTful API. The back-end is a Flask application that provides the RESTful API for the front-end to communicate with.

If you want to host your own instance of Buffet, you will need to install both the front-end and the back-end on your server. A detailed guide on how to install Buffet is provided below. Instructions for installing the front-end, the back-end, and the Docker container are provided in the Docker Compose Installation section. Alternatively, if you just want to install them using the base Docker command, look for the Docker Container Installation in each section.

Front-end Installation

The front-end is a React application that communicates with the back-end using the RESTful API. It is designed to be lightweight, easy to install, and easy to use.

[!NOTE] You can install the front-end on any server that supports Node.js and npm, i.e. on Windows, macOS, or GNU/Linux.

Requirements

• Node.js v20.10.0 or later
• npm 10.4.0 or later

Standard Installation

1. Clone the repository:

git clone https://github.com/kgdn/buffet.git

2. Change into the client directory:

cd client

3. Install the required dependencies:

npm install

4. Create a .env file in the client directory with the following contents:

.env

BROWSER= # none or chrome or firefox or edge or safari
GENERATE_SOURCEMAP= # true or false
BASE_URL= # url of api (e.g. https://localhost)
VITE_MAX_VM_COUNT= # max no. of virtual machines available at any given time

5. Start the development server (optional):

npm run dev

6. Build the production version:

npm run build

7. Deploy the production version to your server using your preferred method, such as Nginx, Apache, or Caddy.

npm run build && cp -r dist/* /path/to/your/webserver/

Docker Container Installation

[!NOTE] This assumes you have followed the steps in the Front-end Installation up until step 4. If you have not done so, please refer to the Front-end Installation section for more details.

It is highly recommended to use the Docker Compose installation method as detailed in the Docker Compose Installation section instead.

1. Modify the nginx/example.conf file to match your desired configuration. Rename it to nginx.conf and save it.

mv example.conf nginx.conf

2. Build the Docker image:

docker build -t buffet-client .

3. Run the Docker container, where ./certs is the path to the SSL certificates:

docker run -v ./certs:/app/certs/ -p 443:443 --name buffet-client -d buffet-client

Back-end Installation

The back-end is a Flask application that provides the RESTful API for the front-end to communicate with, allowing for the creation of virtual machines and querying of database data.

[!NOTE] Unlike the front-end, the back-end is designed to be installed on a GNU/Linux server, as it makes extensive use of QEMU and KVM for virtualization. You can install the back-end on any GNU/Linux distribution that supports Python 3 and pip. Ensure that you have the required dependencies installed before proceeding.

Requirements

• Python 3.12.2 or later
• pip 23.2.1 or later
• venv for Python 3
• QEMU 8.1.3 or later
• Any GNU/Linux distribution for the host operating system
• Virtualization support enabled in the BIOS/UEFI settings
• KVM kernel module loaded

[!TIP] You can check if the KVM kernel module is loaded by running the following command:

lsmod | grep kvm

You should see output similar to the following:

kvm_intel             425984  0
kvm_amd                98304  0
kvm                  1376256  1 kvm_intel
irqbypass              12288  1 kvm

If you do not see any output, you may need to load the KVM kernel module manually:

sudo modprobe kvm

Database Setup

Buffet uses SQLAlchemy to interact with the database. A database is required to store user information and virtual machine information. You can use any SQL database supported by SQLAlchemy, such as SQLite, PostgreSQL, MySQL, and MariaDB. You can use a Docker container for this if you prefer.

• To use SQLite, you can set the SQLALCHEMY_DATABASE_URI variable in the .env file to sqlite:///db.sqlite3. This requires no additional setup.

• To use PostgreSQL, you can set the SQLALCHEMY_DATABASE_URI variable in the .env file to postgresql://username:password@localhost/dbname. This assumes that you have a PostgreSQL database running on your server. You may need to install the psycopg2 package using pip. This is the recommended database for production use.

• To use MySQL/MariaDB, you can set the SQLALCHEMY_DATABASE_URI variable in the .env file to mysql://username:password@localhost/dbname. This assumes that you have a MySQL database running on your server. You may need to install the mysql-connector-python package using pip.

Standard Installation

1. Clone the repository:

git clone https://github.com/kgdn/buffet.git

2. Change into the server directory:

cd server

3. Create a virtual environment:

python3 -m venv .venv

4. Activate the virtual environment:

source .venv/bin/activate

5. Install the required dependencies:

pip install -r requirements.txt

6. Create a .env file in the server directory with the following contents:

.env

SECRET_KEY= # your secret
SQLALCHEMY_DATABASE_URI= # your_database_uri
SQLALCHEMY_TRACK_MODIFICATIONS= # True or False
SQLALCHEMY_ECHO= # True or False
JWT_SECRET_KEY= # your_secret_key
JWT_COOKIE_CSRF_PROTECT= # True or False
JWT_COOKIE_SECURE= # True or False
JWT_TOKEN_LOCATION= # headers, cookies, query_string or json
JWT_ACCESS_TOKEN_EXPIRES= # access_token_expires (int)
JWT_REFRESH_TOKEN_EXPIRES= # refresh_token_expires (int)
CORS_HEADERS= # Content-Type
MAIL_SERVER= # SMTP server
MAIL_PORT= # SMTP port
MAIL_USERNAME= # your email
MAIL_PASSWORD= # your password
MAIL_DEFAULT_SENDER= # your email
MAIL_MAX_EMAILS= # max_emails (int)
MAIL