Getting Started

Getting Started

Get MuxCore running in under a minute. This guide covers installation, configuration, Docker setup, and adding your first module.

---

Quick Start

Install from Source (Go)

go install github.com/Muxcore-Media/core/cmd/muxcored@latest
muxcored

This starts the loom with no modules — just the platform. You'll have a health endpoint at http://localhost:8080/health and a gRPC mesh at :9090. Nothing else happens until you add modules.

With Docker

git clone https://github.com/Muxcore-Media/core.git
cd core
docker compose up

---

Build Presets

Core compiles with zero modules by default. Build tags add module sets:

# Bare loom — zero modules, just the platform
go build ./cmd/muxcored

# Default preset — core modules
go build -tags default ./cmd/muxcored

The default preset imports modules from internal/presets/default.go. To create your own, add a preset file that imports the modules you want.

---

Configuration

Configuration lives in muxcore.json in the working directory. Set MUXCORE_CONFIG to use a custom path. Environment variables override file values.

Minimal Config

{
  "server": {
    "addr": ":8080"
  },
  "grpc": {
    "addr": ":9090"
  },
  "log": {
    "level": "info",
    "format": "text"
  }
}

Full Configuration Reference

Server Settings (server)

Field	Type	Default	Description
addr	string	":8080"	HTTP listen address
read_timeout	int	15	Read timeout in seconds
write_timeout	int	15	Write timeout in seconds
cert_file	string	—	Path to TLS certificate PEM
key_file	string	—	Path to TLS private key PEM

gRPC Settings (grpc)

Field	Type	Default	Description
addr	string	":9090"	gRPC listen address
cert_file	string	—	Path to TLS certificate file
key_file	string	—	Path to TLS private key file
mtls_enabled	bool	false	Require mutual TLS
ca_cert_file	string	—	CA certificate for mTLS client verification
seed_nodes	[]string	—	Existing cluster nodes to join on startup
join_token	string	—	Pre-shared token required to join the cluster

Logging (log)

Field	Type	Default	Description
level	string	"info"	debug, info, warn, error
format	string	"text"	text or json

Database (database)

Field	Type	Default	Description
driver	string	—	Database module driver name
url	string	—	Database connection string

Cache (cache)

Field	Type	Default	Description
driver	string	—	Cache module driver name
url	string	—	Cache connection string

Module Settings (modules)

Arbitrary key-value configuration passed to individual modules:

{
  "modules": {
    "downloader-qbittorrent": {
      "url": "http://localhost:8080",
      "username": "admin"
    }
  }
}

---

Environment Variables

All config fields can be overridden with environment variables. These take highest precedence.

Variable	Overrides	Example
MUXCORE_CONFIG	Config file path	/etc/muxcore/config.json
MUXCORE_ADDR	Server listen address	:3000
MUXCORE_TLS_CERT	HTTP TLS certificate path	/etc/ssl/cert.pem
MUXCORE_TLS_KEY	HTTP TLS private key path	/etc/ssl/key.pem
MUXCORE_LOG_LEVEL	Log level	debug
MUXCORE_LOG_FORMAT	Log format	json
MUXCORE_DATABASE_DRIVER	Database module driver	postgres
MUXCORE_DATABASE_URL	Database connection string	postgres://...
MUXCORE_CACHE_DRIVER	Cache module driver	redis
MUXCORE_CACHE_URL	Cache connection string	redis://...
MUXCORE_GRPC_TLS_CERT	gRPC TLS certificate	/etc/ssl/grpc-cert.pem
MUXCORE_GRPC_TLS_KEY	gRPC TLS private key	/etc/ssl/grpc-key.pem
MUXCORE_GRPC_MTLS_ENABLED	Enable mutual TLS	true
MUXCORE_GRPC_MTLS_CA	mTLS CA certificate	/etc/ssl/ca.pem
MUXCORE_GRPC_SEED_NODES	Cluster seed nodes	node1:9090,node2:9090
MUXCORE_CLUSTER_JOIN_TOKEN	Cluster join token	my-secret-token

---

Adding Modules

Modules are independent Go packages. To add one:

Method 1: Build Tags (Recommended)

Create a preset file that imports your modules:

// internal/presets/mysetup.go
//go:build mysetup

package presets

import (
    _ "github.com/Muxcore-Media/downloader-qbittorrent"
    _ "github.com/Muxcore-Media/media-manager-movies"
)

Build with your tag:

go build -tags mysetup ./cmd/muxcored

Method 2: Custom Main

Create your own main.go that imports modules:

package main

import (
    _ "github.com/Muxcore-Media/downloader-qbittorrent"
    _ "github.com/Muxcore-Media/media-manager-movies"
)

func main() {
    // Bootstrap code — modules auto-register via init()
}

Modules call contracts.Register() in their init() function. Core discovers them at build time.

---

Verifying It Works

# Check the health endpoint
curl http://localhost:8080/health

# Response includes module health statuses:
# {"status":"ok","modules":{"admin-ui":"healthy","api-rest":"healthy"}}

---

Next Steps

• Core Concepts — understand the architecture
• Module System — learn about all module types
• Deployment — single node to multi-machine cluster