Carracho

Carracho is a new native macOS client and server platform for communities built around chat, files, news, messaging and self-hosted servers.

The project takes the ideas that made Carracho distinctive and rebuilds them as a modern application: a single place for persistent server bookmarks, live chat rooms, threaded discussions, file exchange, private conversations, tracker discovery and full server administration.

The macOS client is written in Swift/AppKit and targets macOS 10.15 or newer. A matching server implementation is included for macOS, together with a native headless C server and tracker for Linux.

Strong authenticated encryption

Connections between the new Carracho client and a modern Carracho server use a new authenticated transport designed for confidentiality and tamper detection. Control traffic and transfer-port operations are protected with AES-256-GCM, with fresh session key material negotiated through ephemeral X25519 key agreement.

The modern transport protects far more than login traffic: chat/control packets, file transfers, News transfers, file search, banners and other modern transfer operations all use authenticated encrypted framing. The client also shows the negotiated cipher in the server information panel, so a modern connection can be identified as AES-256-GCM rather than the historical transport.

See the collapsible Security and modern encryption section below for the protocol details.

Current release: 1.1.11

Carracho Client 1.1.11 (build 22) fixes user icons disappearing after an automatic reconnect, sets explicit adaptive text colors in Message Center and improves screenshot attachments in private messages, chat and News. Image preparation now runs outside the UI thread, attachment dialogs belong to their editor window and unavailable upload connections report an error promptly. This is a Client update; Server 1.1.8 (build 19) remains the current Server version.

• Client: 1.1.11 (build 22)
• Server: 1.1.8 (build 19)

The full release notes are available in README_1.1.11.md.

At a glance

Component	Implementation	Purpose
Carracho	Swift / AppKit	Native macOS client
Carracho Server	Swift	Native macOS server
Carracho Server for Linux	C	Headless server for Linux deployments
Carracho Tracker	C	Standalone server-directory service
Classic compatibility	Shared protocol layer	Connects modern Carracho with original/Legacy peers where supported

The modern client combines chat, files, News, private messages, trackers and server administration in one application. Longer feature and implementation notes are grouped below so the README stays useful as an overview instead of becoming a 500-line wall of text.

The new Carracho client

The new client is designed around one main window with a persistent sidebar. Servers, trackers and workspaces stay visible while the active content changes, so the application behaves more like a modern communication client than a collection of separate utility windows.

Server bookmarks and connections

Servers are stored as bookmarks in the sidebar. A bookmark contains the server address, port, account, optional nickname/status overrides and connection behaviour.

The client supports:

• multiple saved server bookmarks;
• live bookmark sessions that can remain connected while another server is selected;
• connection-state and notification indicators directly in the sidebar;
• automatic reconnect after a dropped connection;
• connecting a chosen bookmark when Carracho starts;
• per-bookmark control over offline-message reception;
• bookmark import/export;
• passwords stored in the macOS Keychain rather than normal preferences;
• changing a saved account password directly from the bookmark editor.

On a fresh installation a ready-to-use bookmark for carracho.istation.pw is created with the anonymous account and no password. It is only a first-run default: deleting it does not make it come back later.

Overview

The Overview workspace is the landing page for the selected server. It keeps the important connection and server state close at hand and acts as the starting point for the rest of the client.

Chat rooms

The Chat Rooms workspace provides persistent room navigation and live conversation inside the main window.

Depending on the connected server and account permissions, the client can:

• discover, join, leave and create chat rooms;
• work with room passwords and topics;
• invite users and manage room/member modes;
• show the room participant list alongside the conversation;
• send normal messages, emoji and rich media;
• edit your own modern text messages for up to five minutes after sending, with edited messages marked in the transcript;
• attach images to modern Carracho conversations;
• attach YouTube links with an inline preview/player and a separate link to the original YouTube page;
• keep joined rooms available while switching to another part of the client.

Features that require a modern server are hidden when the connected server does not advertise the corresponding capability.

Files

The Files workspace is a complete browser for the server's published file hierarchy.

It includes:

• directory navigation with history and breadcrumbs;
• server-wide filename search;
• uploads and downloads;
• folder creation and deletion;
• file information and metadata editing where permitted;
• drag-and-drop integration;
• Quick Look preview on macOS;
• Finder integration for completed local downloads;
• direct navigation from Bot File Watcher links into the referenced server folder;
• support for personal directories, Dropbox-style areas and server-side access rules;
• optional server-side approval of completed Guest uploads before they become visible to other users.

The server keeps incomplete uploads separate from published files. A staged upload is exposed under its final name only after the transfer has completed successfully. When Guest uploads require approval is enabled, a completed Guest upload is moved into a hidden pending area instead of the published tree. It is excluded from normal Files listings, downloads, search indexing and Bot File Watcher announcements until an Administrator approves it; rejecting it deletes the pending payload.

Modern and Classic clients can also be given separate file roots when desired. The normal filesRoot is the published file tree used by modern Carracho sessions. An optional legacyFilesRoot can point Classic/Legacy clients at a completely different directory tree on the same server. If legacyFilesRoot is left empty, Classic clients simply use the normal filesRoot as well. This makes it possible to keep one shared file area for everybody or deliberately separate the modern and historical client environments without running two servers.

Transfer Monitor

All transfers are collected in a dedicated Transfers workspace instead of disappearing into background windows.

The monitor distinguishes between the current Mac's transfers and, when the account is allowed to see them, server-wide transfers. It provides:

• active, waiting, paused and finished filters;
• progress, status and transfer-rate information;
• pause, resume and abort actions;
• removal/cleanup of completed entries;
• deletion of abandoned partial data where appropriate;
• persisted monitor state per bookmark;
• resumed transfers without publishing incomplete server files.

News

The modern News workspace turns Carracho news into a forum-style discussion system rather than a flat stream.

It supports:

• news categories;
• threads and replies;
• unread/read tracking;
• background polling and sidebar notification badges for connected bookmarks;
• replying to a specific post;
• editing and deleting posts when permitted;
• reactions;
• image attachments;
• YouTube attachments with inline playback;
• per-category read/post policy;
• modern account permission for posting news.

A separate Classic News view keeps the traditional flat-news stream available where it is needed, while threaded News is the primary interface in the new client.

Message Center

Private communication lives in the Message Center rather than transient pop-up windows.

The client keeps conversations locally so they remain useful after switching workspaces or restarting the app. It includes:

• conversation history;
• unread counters;
• search;
• new-message composition;
• per-conversation cleanup/deletion;
• online private messages;
• modern offline messages for users who are currently disconnected;
• five-minute editing of your own modern text Private Messages, with edit state preserved in local conversation history.

Message editing is a modern text-message feature. Messages containing image or other media references are not editable, and Classic/Legacy peers continue to use the historical message protocol unchanged.

Offline messages on the modern server are stored in SQLite with authenticated encryption and are removed from the server after successful delivery/acknowledgement.

Users and presence

The client presents connected users as people rather than protocol records. Depending on server capabilities it can display and update:

• nickname and account identity;
• presence/sleep state;
• status message;
• e-mail and About Me information;
• avatar/picture;
• account/group colour;
• extended user information.

Accounts with the appropriate rights can also disconnect or ban users and send broadcasts.

Tracker browser

Trackers provide a decentralized server directory, and the new client gives them a proper browser in the sidebar.

Tracker bookmarks can be added, edited and removed independently from server bookmarks. Results refresh automatically and a server can be opened directly from the tracker listing.

A fresh client starts with carracho.istation.pw as its initial tracker. As with the default server bookmark, this is only created once and can be removed permanently.

Administration

Administration is integrated into the same client. Pages appear according to the permissions of the connected account, instead of forcing administrators into a separate tool.

The current administration workspaces include:

• Accounts — users, groups, per-account overrides, colours and permissions;
• News Categories — categories, retention and access policy;
• Server Info — server identity, description and banner;
• Trackers — publication, tracker targets, privacy and advertised bandwidth class;
• Server Log — protocol and runtime activity;
• Events — user activity audit trail;
• Bot — local Bot runtime, automatic greeting, command rules, RSS/Atom feeds and File Watchers;
• Advanced — limits, file/search settings, IP rules, authentication mode, File Watcher Guest visibility and Guest upload approval with a pending-upload queue;
• Agreement — login agreement text;
• Statistics — server and transfer counters.

The permission model also includes new account-level rights such as Post News, allowing modern server features to be controlled independently and extended over time.

Server Bot

Modern Carracho servers include a local server Bot that runs as a server-owned session rather than as a normal network login. Administrators can control it from the Bot page in the client without editing configuration files by hand.

The Bot administration page provides:

• enable/disable control for the local Bot;
• an optional automatic greeting for newly connected users;
• configurable greeting text with {name} and {login} placeholders;
• persistent command/response rules, each with its own enable/disable switch;
• RSS/Atom feed management with per-feed target room, polling interval, summary length and image setting;
• File Watchers with per-watcher folder, target Conference, enable/disable state and announcement template;
• a feed test action that publishes the fetched article into Public using the same rendering path as a normal RSS post.

Bot commands

Command rules are simple server-side responses rather than a scripting language. A rule can map a command such as Hello to a response such as Hello {name}, how are you?.

In a Conference the Bot is addressed with # at the beginning of the message:

#Hello

A direct Private Message to the Bot does not need the prefix:

Hello

The Bot replies in the same Conference in which it was addressed, or directly to the sender for a Private Message. If necessary it joins the target Conference first and follows the normal speaking permissions of that room. Sending a Bot message also wakes the Bot from its sleeping presence state.

File Watchers

File Watchers let the server Bot announce newly created files and folders from the normal published Files tree. Each watcher can independently define:

• enabled/disabled state;
• a folder relative to the server's normal filesRoot;
• a target Conference;
• an announcement template.

Use . as the watched path to monitor the Files root itself. Watchers are recursive below their configured path and validate that the resolved directory remains inside the Files root.

Announcement templates support two placeholders:

{folder}
{file}

{folder} becomes a clickable Carracho Files link to the affected folder, while {file} expands to the detected file or folder name. For example:

New {file} in {folder}

The client understands the generated carracho-file:/// links and opens the referenced location directly in the Files workspace. By default, File Watcher announcements are delivered to Account Holder and Administrator members of the selected Conference. An Advanced server setting can additionally allow Guest members to receive them. Filesystem event bursts are coalesced before posting, and repeated announcements for the same watcher/folder are rate-limited.

Guest upload approval

Administrators can optionally enable Guest uploads require approval in Administration → Advanced. With this setting off, uploads behave as before. With it on, only uploads from Guest accounts are moderated; Account Holder and Administrator uploads are still published immediately.

A completed Guest upload is kept in a hidden server-side pending area on the same filesystem as its intended destination. The client shows pending items with their destination, uploader, size and upload time, together with Approve, Reject and Refresh actions. Approval atomically publishes the payload under its intended final name and then makes it eligible for search indexing and File Watcher announcements. Rejection permanently deletes the pending payload.

Pending destination names remain reserved while awaiting a decision so another upload cannot silently take the same final path. The queue survives server restarts on both the Swift/macOS and native Linux servers.

A modern Guest uploader is notified after the server has fully accepted the completed payload into the approval queue. For folder uploads, this happens once for the whole folder and only after every contained file and subfolder has been transferred successfully.

The macOS server uses native filesystem event sources. The native Linux server implements the same feature with inotify.

RSS and Atom feeds

The Bot can monitor multiple RSS 2.0 and Atom feeds and publish newly discovered articles into configured Conferences. Each feed can independently define:

• enabled/disabled state;
• display name;
• RSS/Atom URL;
• target Conference;
• polling interval;
• maximum summary length;
• whether an article image should be included when the feed provides one.

MacRumors and Tarnkappe are available as convenient presets in the administration UI, but feeds are not provider-specific and arbitrary compatible RSS/Atom URLs can be added.

For each new article the Bot publishes the headline, a cleaned and shortened description, the original article link and, when enabled and available, an image stored through the normal Carracho media system. Common feed boilerplate such as WordPress “appeared first on” footers is removed from the summary.

Feed state is persistent. On the first successful poll of a newly configured feed, existing items are recorded as already seen instead of being dumped into a room as an old backlog. Later polls publish only unseen items, and servers use ETag / Last-Modified conditional requests when the feed origin supports them.

RSS fetching is deliberately restricted to HTTP/HTTPS and rejects local or reserved network destinations, unsafe redirects, oversized responses and stalled requests. This allows administrators to add external feeds without turning the Bot into an accidental internal-network fetch proxy.

Settings, appearance and notifications

The client has its own settings window with General and Sounds sections.

General settings cover the global client identity, avatar, About Me information and the default download destination. Sounds can be configured per event, including custom imported sound files, volume and macOS notifications.

The application also provides system/light/dark appearance choices, English and German localization, and Sparkle-based update support.

Security and modern encryption

Security is a first-class part of the new Carracho client/server protocol. When two modern Carracho peers connect, the client negotiates the modern authenticated transport automatically. It does not merely replace one cipher with another: the handshake, key separation, frame authentication and password storage model are all different from the historical transport.

Authenticated session handshake

Each modern connection creates fresh ephemeral X25519 key pairs on the client and server. The shared secret is combined with the authenticated login session material and a fresh 32-byte server session salt to derive a transport master key.

The server also authenticates the handshake transcript with HMAC-SHA256. The authenticator covers the login challenge, both X25519 public keys and the session salt. The client verifies this before accepting the modern transport. A connection that cannot complete that authenticated negotiation is not silently accepted as a modern encrypted session.

Because the X25519 keys are ephemeral and newly generated for a connection, transport keys are not static server keys reused from session to session.

HKDF-SHA256 key derivation and key separation

Carracho derives 256-bit transport keys using HKDF-SHA256. Separate keys are produced for the two directions of the control channel:

• client → server;
• server → client.

Transfer connections receive their own derived keys as well. Their derivation is bound to the session salt, a fresh per-transfer 16-byte nonce, the transfer operation and the traffic direction. A file download therefore does not reuse the same AES key material as a control packet, a News upload or traffic flowing in the opposite direction.

AES-256-GCM authenticated framing

Modern control and transfer traffic is protected with AES-256-GCM. Every frame carries a 128-bit authentication tag. The frame length, protocol domain and monotonic sequence number are authenticated as additional data, so modifying ciphertext or authenticated frame metadata causes verification to fail rather than producing unauthenticated plaintext.

Each direction keeps its own sequence counter. The receiver requires exactly the expected sequence number, providing protection against replay, duplication and attempts to splice authenticated frames into a different position in the stream. Control and transfer traffic also use separate protocol domains when authenticated.

The authenticated transport is used for modern:

• control/session traffic and chat commands;
• file uploads and downloads;
• News article transfers;
• media transfer operations;
• file search;
• banner transfer;
• other operations carried over the transfer connection.

In other words, encryption is not a decorative lock icon applied only to the login form. The actual application traffic is encrypted and authenticated on the wire.

Password protection on the server

Modern server accounts use versioned PBKDF2-HMAC-SHA256 password verifiers with a random 16-byte salt, a 256-bit derived value and currently 210,000 iterations. Verification is performed with a constant-time comparison. The stored verifier format is parameterized so the work factor can be raised in the future without changing the account schema.

The server can run in modernOnly authentication mode. In that mode password-equivalent material needed only for old clients is removed from persisted accounts, leaving the modern password verifier as the authentication representation.

Encrypted offline-message storage

Offline messages stored by the modern server are also protected at rest. Their payloads are sealed with AES-GCM using a server-side 256-bit key, and message/account identity is included as authenticated additional data. A modified stored message therefore fails authentication instead of being delivered as valid plaintext.

What this security model means

For a modern client talking to a modern server, Carracho provides authenticated encryption between the client and server: passive network observers cannot read protected application traffic, and modified authenticated frames are rejected.

This is transport encryption between client and server, not end-to-end encryption between individual users. The server necessarily processes chat, News, files and messages in order to provide the Carracho service.

Server options

The repository contains two implementations of the current Carracho server:

Carracho Server for macOS

The Xcode project includes the Carracho Server target. It uses the same Swift server core/runtime as the client-side development environment and stores its instance under:

~/Library/Application Support/Carracho/Server/

The normal layout is:

Server/
├── etc/
│   ├── carracho-server.json
│   └── carracho-bot.json
├── db/
│   ├── server.db
│   ├── file-index.db
│   └── bot-rss.db
├── logs/
│   └── carracho-server.log
└── ...

Native Linux server

ServerLinux/ contains a native C implementation intended for headless deployment. It does not require a Swift runtime and uses OpenSSL, json-c, SQLite, libcurl and libxml2. Modern server features such as message editing, Bot File Watchers and Guest upload approval are implemented alongside the Swift/macOS runtime; Linux File Watchers use native inotify events.

Compilation of the native Linux components is documented in the Building on Linux section below.

The server listens on the configured control port, normally 6700; the adjacent port is used for transfer connections. The standalone tracker defaults to port 6702.

First server start

A fresh server database contains two initial accounts:

• admin — administrator account, initially with an empty password;
• anonymous — restricted guest account, initially with an empty password.

Change the administrator password before exposing a new server to an untrusted network.

Bot configuration and persistence

The Bot has its own persistent configuration in etc/carracho-bot.json. The macOS and native Linux server implementations use the same conceptual settings so Bot administration behaves consistently on both platforms.

A minimal configuration looks like this:

{
  "enabled": false,
  "avatarPath": "etc/carracho-bot-avatar.png",
  "greetNewUsers": false,
  "greetingTemplate": "Welcome, {name}! Nice to have you here.",
  "commandRules": [],
  "rssFeeds": [],
  "fileWatchers": []
}

Normal administration should be done through the Carracho client's Administration → Bot page. The JSON file remains useful for deployment, backups and headless server provisioning.

Command rules, RSS feed definitions and File Watcher definitions are stored in this Bot configuration. File Watcher changes made through the client administration UI are persisted there and reloaded by the running server. RSS polling state and seen-item tracking are stored separately in db/bot-rss.db, so restarting the server does not cause previously seen articles to be published again.

The main runtime configuration lives in etc/carracho-server.json. A typical configuration contains the server name, description, port, published file roots, authentication mode, connection/transfer limits, search exclusions, news expiration settings and tracker publication settings.

Two file-root settings are available:

• filesRoot — the primary published file tree used by modern Carracho clients;
• legacyFilesRoot — an optional second tree used only by Classic/Legacy client sessions.

When legacyFilesRoot is empty, Classic/Legacy sessions fall back to filesRoot. When it is configured, the server selects the appropriate root automatically from the negotiated client transport. Both roots may point at separate disks or mounted filesystems.

For example:

{
  "filesRoot": "../Files",
  "legacyFilesRoot": "../Files-Legacy"
}

The SQLite databases remain in the fixed db/ directory beside the server installation. The published file trees are independent of the database location.

Tracker

TrackerLinux/ contains the native tracker service. It is built together with the native server by the Linux build described below, or separately with make tracker.

Start the compiled tracker directly with:

.build/linux/carracho-tracker --port 6702

Server registrations expire when they are no longer refreshed.

A note about Classic Carracho compatibility

Compatibility with original Carracho software is intentionally treated as a bridge, not as the definition of the new project.

The practical side effect of keeping the protocol lineage intact is useful:

• the new macOS client can connect to many original/Classic Carracho servers;
• the modern server can accept original Carracho clients when authenticationMode is legacyCompatible;
• Classic trackers, files, chat, user administration and other reconstructed protocol areas remain available;
• when a Classic peer is detected, modern-only capabilities are hidden or mapped to the older behaviour automatically;
• a server can optionally expose a separate legacyFilesRoot to Classic clients while modern clients continue to use the primary filesRoot.

Classic connections use the historical transport and the limits of the historical protocol. Features invented for the new platform, such as modern authenticated transport, threaded-News extensions, reactions, rich-media capability negotiation, offline-message extensions, message editing, Bot File Watcher administration and new account permissions, require a modern Carracho peer. Modern message-edit packets are never sent to Classic clients, preserving the historical chat and Private Message packet layouts.

Servers can also be configured as modernOnly. In that mode the compatibility password material required by original clients is not retained, so Classic authentication is deliberately unavailable.

Building on Linux

The native Linux build produces the headless Carracho Server and Carracho Tracker. The macOS GUI client is not part of the Linux build.

Build requirements

A normal build needs:

• a C11 compiler such as GCC or Clang;
• make and a POSIX shell;
• pkg-config;
• OpenSSL development headers and libraries;
• json-c;
• SQLite 3;
• libcurl;
• libxml2;
• pthread support supplied by the system C library.

On Debian 12 or newer and Ubuntu 22.04 or newer, install the required development packages with:

sudo apt update
sudo apt install \
  build-essential \
  pkg-config \
  libssl-dev \
  libjson-c-dev \
  libsqlite3-dev \
  libcurl4-openssl-dev \
  libxml2-dev

These package names are shared by current Debian and Ubuntu releases. Other Linux distributions need the equivalent development packages. The build scripts use pkg-config to obtain the compiler and linker flags.

Build server and tracker

From the repository root:

make native

For the stricter development build used by this project:

make native-werror

native-werror builds both components with the normal warning set plus -Werror.

The two components can also be built separately:

make server
make tracker

The scripts can be called directly as well:

./ServerLinux/build.sh
./TrackerLinux/build.sh

To use a different C compiler:

CC=clang make native

Optional WebAdmin helper

The native server itself builds without Python. The bundled WebAdmin frontend uses a separate PyInstaller ONEFILE helper. Only the build machine needs Python for this step; the generated helper contains its own Python runtime.

On Debian 12+ and Ubuntu 22.04+:

sudo apt install python3 python3-venv python3-dev

Using python3-dev instead of a version-specific libpython3.x package keeps the build instructions portable across distributions with different default Python versions.

Build and stage the helper with:

./ServerLinux/Webinterface/scripts/linux-build-phase.sh \
  .build/linux/libexec/carracho

On the first build the script creates a private virtual environment below ServerLinux/Webinterface/.linux-build/ and installs the required PyInstaller version there.

Build output

After building the native components, the relevant output is under:

.build/linux/
├── carracho-server
├── carracho-tracker
├── etc/
│   ├── carracho-server.json
│   └── carracho-bot.json
├── db/
└── libexec/
    └── carracho/
        └── carracho-web-admin-helper   # only when the optional helper was built

The databases inside db/ are created as the server runs; they are not prebuilt artifacts.

The server resolves its default configuration relative to its executable, so the development build can be started directly:

.build/linux/carracho-server

An explicit configuration file can also be supplied:

.build/linux/carracho-server \
  --config .build/linux/etc/carracho-server.json

Start the tracker with:

.build/linux/carracho-tracker --port 6702

Install as systemd services

For a permanent Linux installation, a simple layout is /opt/carracho with a dedicated unprivileged carracho user.

Create the service account and install the initial build:

sudo useradd --system --home /opt/carracho --shell /usr/sbin/nologin carracho
sudo install -d -o carracho -g carracho /opt/carracho
sudo cp -a .build/linux/. /opt/carracho/
sudo chown -R carracho:carracho /opt/carracho

The user that runs the server must have full access to the entire /opt/carracho tree: it must be able to read files, write files, create and remove entries, and traverse all required subdirectories. With the example service above that user is carracho, so /opt/carracho should remain owned by carracho:carracho, as shown by the chown -R command. If you configure a different User= or Group= in the systemd service, adjust the ownership and permissions of /opt/carracho accordingly. Do not solve this by making the directory world-writable.

This access is required for databases, logs, uploaded files, persistent state, Bot data and administration changes that are mirrored back to etc/carracho-server.json.

Create /etc/systemd/system/carracho.service:

[Unit]
Description=Carracho Server
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=carracho
Group=carracho
WorkingDirectory=/opt/carracho
ExecStart=/opt/carracho/carracho-server --config /opt/carracho/etc/carracho-server.json
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

If the standalone tracker should run on the same machine, create /etc/systemd/system/carracho-tracker.service:

[Unit]
Description=Carracho Tracker
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=carracho
Group=carracho
WorkingDirectory=/opt/carracho
ExecStart=/opt/carracho/carracho-tracker --port 6702
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Reload systemd and enable the services:

sudo systemctl daemon-reload
sudo systemctl enable --now carracho.service
sudo systemctl enable --now carracho-tracker.service

If the tracker is not needed on that host, simply omit carracho-tracker.service.

Check service state and follow the logs with:

systemctl status carracho.service --no-pager
systemctl status carracho-tracker.service --no-pager

journalctl -u carracho.service -f
journalctl -u carracho-tracker.service -f

With the default ports, the firewall/NAT rules normally need:

6700/tcp   Carracho control connection
6701/tcp   Carracho transfer connections
6702/tcp   Tracker queries
6702/udp   Tracker server registrations

For example with UFW:

sudo ufw allow 6700/tcp
sudo ufw allow 6701/tcp
sudo ufw allow 6702/tcp
sudo ufw allow 6702/udp

The WebAdmin does not need its own systemd service. When it is enabled, carracho-server starts the bundled helper as a child process. If an environment file is used for the WebAdmin token, add a systemd drop-in for carracho.service as documented in ServerLinux/Webinterface/README.md.

Updating an existing service installation

Do not replace the live etc/ or db/ directories with fresh build defaults. Stop the services, replace only the binaries (and the optional WebAdmin helper), then start them again:

sudo systemctl stop carracho.service carracho-tracker.service

sudo install -m 0755 .build/linux/carracho-server /opt/carracho/carracho-server
sudo install -m 0755 .build/linux/carracho-tracker /opt/carracho/carracho-tracker

# Only when the optional helper was built:
sudo install -d -o carracho -g carracho /opt/carracho/libexec/carracho
sudo install -m 0755 .build/linux/libexec/carracho/carracho-web-admin-helper \
  /opt/carracho/libexec/carracho/carracho-web-admin-helper

sudo chown carracho:carracho \
  /opt/carracho/carracho-server \
  /opt/carracho/carracho-tracker

sudo systemctl start carracho.service carracho-tracker.service

That preserves the live configuration, accounts, databases and server state under /opt/carracho.

Remove generated native build output with:

make clean

Building the macOS client

Requirements: macOS with Xcode.

xcodebuild -project Carracho.xcodeproj \
  -scheme Carracho \
  -configuration Debug \
  CODE_SIGNING_ALLOWED=NO build

For normal development, open Carracho.xcodeproj and run the shared Carracho scheme.

The project currently targets macOS 10.15 or newer.

Repository layout

Carracho/
├── Client/          Client-side storage, media, sounds, bookmarks and UI support
├── Gui/             Main macOS workspaces and administration UI
├── LegacyProtocol/  Protocol codecs and compatibility primitives
├── Networking/      Client networking for control, files, news, media and trackers
├── ServerCore/      Server state, persistence, authentication and shared backend
└── ServerRuntime/   Swift server runtime

ServerLinux/          Native C headless server
TrackerLinux/         Native C tracker
Analysis/spec/        Protocol and server documentation
Analysis/tests/       Swift and native integration/regression tests

Tests

Run the Swift/reference protocol suite:

make swift-tests

Run the native C integration suite:

make c-tests

Run the complete local release gate:

make release-check

The native C server and tracker are expected to compile cleanly with -Wall -Wextra -Wpedantic -Werror.

Protocol and implementation documentation

Detailed implementation notes live under Analysis/spec/.

Useful starting points are:

• Analysis/spec/PROTOCOL.md
• Analysis/spec/SERVER_RUNTIME.md
• Analysis/spec/FILE_BACKEND.md
• Analysis/spec/NEWS_BACKEND.md
• Analysis/spec/MODERN_SERVER_STATE.md

These documents describe the wire protocol, persistence model and compatibility work in much more detail than the user-facing overview above.