Skip to content

QUICKSTART.md

Latest commit

 

History

History
138 lines (95 loc) · 5.7 KB

QUICKSTART.md

File metadata and controls

138 lines (95 loc) · 5.7 KB

marchat quickstart

Get a server and client running in a few minutes. For full detail, see README.md.

What you need

  • Server: MARCHAT_ADMIN_KEY (secret) and MARCHAT_USERS (comma-separated admin usernames). No other env vars are required for a local trial.
  • Client: A username and the WebSocket URL (default path is /ws).
  • Optional: Go 1.25.9+ only if you build from source; openssl (or any way to produce 64 hex chars) to generate the admin key.

1. Install binaries

Pick one:

  • GitHub releases: Download the zip for your OS/arch from releases, unpack, and use marchat-server and marchat-client. Termux (aarch64): use linux-arm64 (same static GOOS=linux build as Linux ARM64 servers).

  • Windows (PowerShell):

    iwr -useb https://raw.githubusercontent.com/Cod-e-Codes/marchat/main/install.ps1 | iex

  • Docker: docker pull codecodesxyz/marchat (pin a tag in production; see README.md).

  • Homebrew (tap): brew tap cod-e-codes/marchat then brew install marchat.

  • Scoop (bucket): scoop bucket add marchat https://github.com/Cod-e-Codes/scoop-marchat then scoop install marchat.

  • winget: winget install Cod-e-Codes.Marchat. Maintainer workflow and checksums: PACKAGING.md.

2. Create secrets

openssl rand -hex 32

Use the output as MARCHAT_ADMIN_KEY. Choose admin usernames (e.g. alice,bob) for MARCHAT_USERS.

3. Run the server

Environment variables (simplest)

export MARCHAT_ADMIN_KEY="<paste-hex-key>"
export MARCHAT_USERS="alice,bob"
./marchat-server

Default listen port is 8080 (all interfaces, :8080). Optional: --admin-panel or --web-panel for admin UIs (see README.md).

--interactive: Runs the first-time setup wizard only if MARCHAT_ADMIN_KEY or MARCHAT_USERS is missing (unset in the environment and not supplied in config/.env). If both are already configured, this flag has no extra effect: the server starts like ./marchat-server. Without required config and without --interactive, the server exits with an error pointing you to set env vars or use --interactive.

Config file (repo / long-running)

From the repo (or any layout where the server’s config dir is config/):

cp env.example config/.env
# Edit config/.env: set MARCHAT_ADMIN_KEY and MARCHAT_USERS
./marchat-server

The server reads config/.env with overload semantics: keys present in the file override the same variables already in the process environment. Restart after edits. See README.md.

Docker (one container)

docker run -d -p 8080:8080 \
  -e MARCHAT_ADMIN_KEY="$(openssl rand -hex 32)" \
  -e MARCHAT_USERS=alice,bob \
  codecodesxyz/marchat

Docker Compose

The sample docker-compose.yml exposes the port and database volume; you must add MARCHAT_ADMIN_KEY and MARCHAT_USERS (for example via a gitignored .env next to the compose file). See README.md.

4. Connect the client

Default URL: ws://localhost:8080/ws.

Admin (can run admin commands after auth):

./marchat-client --username alice --admin --admin-key "<same-as-MARCHAT_ADMIN_KEY>" --server ws://localhost:8080/ws

Regular user:

./marchat-client --username user1 --server ws://localhost:8080/ws

Or run ./marchat-client with no flags and use the interactive config flow.

For optional graphical clients, see README.md.

TLS / wss://: Set MARCHAT_TLS_CERT_FILE and MARCHAT_TLS_KEY_FILE on the server, or put Caddy (or another proxy) in front. Local Caddy + helper scripts: deploy/CADDY-REVERSE-PROXY.md.

5. Build from source (optional)

git clone https://github.com/Cod-e-Codes/marchat.git && cd marchat
go mod tidy
go build -o marchat-server ./cmd/server
go build -o marchat-client ./client

Linux clipboard for the client: install xclip (or your distro’s equivalent). See README.md.

6. Verify and troubleshoot

./marchat-server -doctor
./marchat-client -doctor

Use -doctor-json for machine-readable output. To skip the GitHub “latest release” check: MARCHAT_DOCTOR_NO_NETWORK=1. See README.md and ARCHITECTURE.md.

7. First minutes in the TUI

  • Ctrl+H: help overlay.
  • Channels: You start in #general; use :join <name>, :leave, :channels.
  • DMs: :dm (see README.md).
  • Quit: :q or your terminal’s usual exit.

Where to read next

Topic Doc
Doc index docs/README.md
Release history CHANGELOG.md
All options, commands, hotkeys README.md
Components, config paths, doctor ARCHITECTURE.md
WebSocket message shapes PROTOCOL.md
Threat model, reporting SECURITY.md
Themes THEMES.md
Desktop / bell / quiet hours NOTIFICATIONS.md
Plugins PLUGIN_ECOSYSTEM.md, plugin/README.md, marchat-plugins
Tests and CI expectations TESTING.md
Package managers PACKAGING.md
Contributing CONTRIBUTING.md