Documentation - Carbon

Requirements

Before installing Carbon, ensure your system meets the following requirements:

System Requirements

Operating System: Linux
Memory: Minimum 512MB RAM (1GB recommended)
Disk Space: 50MB for installation

Software Requirements

Docker: Version 20.10 or higher (for Docker installation)
Gcc: Version 13.3.0 or higher (for building from source)
Make: Required for building from source (easier)

Docker Installation

The recommended way to install Carbon is using Docker for quick setup and isolation.

Pull the Image

docker pull azreyo/carbon:latest

Run the Container

docker run -d -p 8080:8080 azreyo/carbon:latest

Verify Installation

Open your browser and navigate to http://localhost:8080

Install From Source

For developers who want to build Carbon from source code.

Clone the Repository

git clone https://github.com/Azreyo/Carbon.git
cd Carbon

Build the Project

Install necessary packages first to be able to build it from source code.

Ubuntu / Debian:

# Update package lists
sudo apt-get update

# Install required dependencies
sudo apt-get install -y \
    build-essential \
    libssl-dev \
    libmagic-dev \
    libnghttp2-dev \
    zlib1g-dev \
    pkg-config

Fedora / RHEL / CentOS

# Update system
sudo dnf update -y

# Install dependencies
sudo dnf install -y \
    gcc \
    gcc-c++ \
    make \
    openssl-devel \
    file-libs \
    libnghttp2-devel \
    zlib-devel \
    pkgconf-pkg-config

Arch Linux / Manjaro

# Update system
sudo pacman -Syu

# Install dependencies
sudo pacman -S --needed \
    base-devel \
    openssl \
    file \
    nghttp2 \
    zlib \
    pkgconf

Manual compilation:

gcc src/server.c src/config_parser.c src/server_config.c src/websocket.c src/http2.c src/performance.c -o carbon \
    -D_GNU_SOURCE \
    -Wall -Wextra -O2 \
    -lssl -lcrypto -lpthread -lmagic -lnghttp2 -lz

Or with automated make compilation (only available for ubunut / debian):

make build

Run Carbon

./carbon

Quick Start

Start using Carbon in minutes with this quick guide.

Basic Usage

Once installed, you can start the Carbon server with:

./carbon

Your First Project

Create a new directory for your project
Add your static files (HTML, CSS, JS)
Point Carbon to your directory
Access your site at localhost:8080

Configuration File

Configure Carbon to suit your needs with a configuration file.

Create Configuration

Create a config.conf file in your project root:

running = true
port = 8080
use_https = false
enable_http2 = false
server_name = 0.0.0.0
log_file = log/server.log
verbose = true
www_path = www

Available Options

port - Server port (default: 8080)
server_name - Server host (default: 0.0.0.0)
www_path - Document WWW directory
use_https - Enable/disable https
enable_http2 - Enable/disable http2

Config Variables

Override configuration using config variables in config file.

Available Variables

port - Server port (default: 8080)
server_name - Server host (default: 0.0.0.0)
www_path - WWW root directory
use_https - Enable htpps (true/false)
enable_http2 - Enable http2 (true/false)

Websocket

Programmatic configuration options for advanced use cases.

Basic Example

// Connect to WebSocket server
const ws = new WebSocket('ws://localhost:8080');

// Connection opened
ws.addEventListener('open', (event) => {
    console.log('Connected to server');
    ws.send('Hello Server!');
});

// Listen for messages
ws.addEventListener('message', (event) => {
    console.log('Message from server:', event.data);
});

// Handle errors
ws.addEventListener('error', (error) => {
    console.error('WebSocket error:', error);
});

// Connection closed
ws.addEventListener('close', (event) => {
    console.log('Disconnected from server');
});

Docker Deployment

Deploy your Carbon server to production environments using Docker.

Docker Compose

Deploy using Docker Compose for production:

version: '3.8'

services:
  carbon-server:
    image: azreyo/carbon:latest
    container_name: carbon-http-server
    ports:
      - "8080:8080"
      - "8443:8443"
    environment:
      - SERVER_NAME=0.0.0.0
      - PORT=8080
      - USE_HTTPS=false
      - ENABLE_HTTP2=false
      - ENABLE_WEBSOCKET=false
      - MAX_THREADS=4
      - VERBOSE=true
    restart: unless-stopped

networks:
  carbon-net:
    driver: bridge

Port Already in Use

If you encounter a "port already in use" error, either stop the conflicting service or use a different port

Check in configuration file what port are you using.

port = 8080

Find Process Using Port

sudo lsof -i :8080
            
# Or use netstat
sudo netstat -tulpn | grep 8080

Permission Denied

On Linux, you may need to use sudo for ports below 1024, or run as a privileged user.

Solutions

Use a port above 1024 (recommended)
Run with sudo (not recommended for production)
Use setcap to grant port binding capabilities

Using setcap

sudo setcap 'cap_net_bind_service=+ep' /path/to/carbon

Static Files Not Loading

Ensure your document root is correctly configured and files have proper read permissions.

Check Permissions

chmod -R 644 /path/to/carbon/*
chmod 755 /path/to/carbon/

Verify Configuration

Make sure your config.conf points to the correct directory:

www_path = /path/to/carbon/

Carbon Documentation