snip-sync 0.2.0

gRPC sync server for snp snippet manager
Documentation

snip-sync server

snip-sync is the optional, self-hostable gRPC server used by the snp client. Snippet descriptions, commands, and tags are encrypted by the client before upload; the server stores ciphertext plus the metadata needed to synchronize libraries.

snip-sync deliberately does not terminate TLS. It serves plaintext gRPC and HTTP, normally on loopback, and should sit behind a TLS-terminating reverse proxy for a remote deployment. TLS_ENABLED=true only acknowledges that an upstream proxy is providing TLS; it does not turn on TLS inside snip-sync.

Local quickstart

This is the shortest path for trying the client and server on one machine.

# Install both verified release binaries (skip either command if already installed).
curl -fsSL https://raw.githubusercontent.com/eggstack/snip-it/main/packaging/install.sh | bash -s -- --both

# Cargo is the source/package fallback when a host has no prebuilt asset.
# cargo install snip-it snip-sync

# Create the platform-specific config, database, state, and data directories.
# Certificates are not needed for direct loopback development.
snip-sync init --skip-cert

# Keep this in a terminal while using the client.
SNIP_SYNC_ALLOW_HTTP=true snip-sync serve

The bootstrap installer initializes missing server layout/config without overwriting existing data. On releases containing the lifecycle installer, register startup with the server itself so the appropriate supervisor is selected for the host:

snip-sync startup instructions
snip-sync startup install

Startup registration is intentionally owned by snip-sync; the binary installer does not duplicate systemd, launchd, cron, or Task Scheduler templates. If an older installed binary does not expose startup, upgrade it or follow the manual supervisor examples below.

In another terminal, register the client and sync:

snp register --server http://127.0.0.1:50051
snp sync run --push-only

Registration creates the account, stores the server URL and device ID in the client config, and stores the API key in the OS keychain when available. Run snp register --force only when you intentionally want a new account and key; it does not join an existing account.

For multiple environments, register once, then securely provision that same API key, server URL, and a unique device ID to each environment that should share the libraries. Registering each environment independently creates isolated accounts. After the first client seeds the server, use snp sync run --pull-only on new environments and then set sync_direction = "Bidirectional" in the client sync.toml for normal use. See USER_GUIDE.md for the client-side settings example.

The server config location is platform-specific. Run this to see the exact paths in use:

snip-sync paths
snip-sync edit

The server defaults to gRPC 127.0.0.1:50051, HTTP health/metrics 127.0.0.1:50050, and a SQLite database under the platform data/config area. The initialized premade directory is also shown by snip-sync paths.

Lifecycle commands

Use snip-sync stop to stop the local server and snip-sync restart to stop and start it again. If startup registration exists, restart delegates to that manager and performs a bounded health check. On Unix, both commands accept the current structured PID record and older numeric PID files. A dead numeric PID is cleaned only after the server singleton lock is acquired; a live process whose name is not snip-sync is refused unless --force is supplied. The persistent snip-sync.server.lock file may remain after shutdown because its kernel lock, not file existence, records ownership.

Register boot startup with the server itself. instructions is read-only and prints the exact rendered unit, plist, cron block, or Task Scheduler commands:

snip-sync startup instructions
snip-sync startup install
snip-sync startup uninstall

Auto mode selects a running systemd host on Linux, cron otherwise, launchd on macOS, and Task Scheduler on Windows. Systemd and launchd installation use the intended non-root account and print an exact sudo command when elevation is needed; they never silently fall back to cron. Cron and Task Scheduler invoke croncheck, not serve directly. Startup registration persists only small manager metadata under the state directory and never removes the binary, database, configuration, certificates, or premade libraries.

To generate local certificate assets for a reverse-proxy experiment:

snip-sync cert

This writes cert.pem and key.pem under the reported certificate directory. They are self-signed development assets for a proxy, not production certificates, and are not read directly by snip-sync.

Production deployment

Use a real certificate from a trusted CA at the reverse proxy and forward gRPC over cleartext HTTP/2 (h2c) to the loopback server. For example, Caddy can use:

sync.example.com {
    reverse_proxy h2c://127.0.0.1:50051
}

Keep the server bound to loopback in snip-sync and register it with the appropriate supervisor:

snip-sync startup instructions --method systemd
snip-sync startup install --method systemd

For manual systemd execution, the equivalent unit is:

# /etc/systemd/system/snip-sync.service
[Unit]
Description=snip-sync gRPC server
After=network.target

[Service]
Type=simple
User=snip-sync
ExecStart=/usr/local/bin/snip-sync serve
Environment=CONFIG_PATH=/etc/snip-sync/config.toml
Environment=TLS_ENABLED=true
Environment=DATABASE_URL=/var/lib/snip-sync/snippets.db
Environment=PREMADE_DIR=/var/lib/snip-sync/premade-libraries
Restart=on-failure

[Install]
WantedBy=multi-user.target

TLS_ENABLED=true is appropriate here because the proxy terminates TLS. The server process itself remains plaintext and should not be exposed directly to the public network.

sudo install -d -o snip-sync -g snip-sync /etc/snip-sync /var/lib/snip-sync/premade-libraries
sudo -u snip-sync env CONFIG_PATH=/etc/snip-sync/config.toml /usr/local/bin/snip-sync init --skip-cert
sudo systemctl daemon-reload
sudo systemctl enable --now snip-sync

Register the client using the proxy's HTTPS URL, not the backend port:

snp register --server https://sync.example.com
snp sync run --push-only

The client uses the operating system's trusted certificate roots for HTTPS, so use a publicly trusted certificate for a remote deployment. A self-signed certificate generated by snip-sync cert is intended for local proxy testing.

Configuration

The default config path is the platform config directory shown by snip-sync paths. Set CONFIG_PATH to use a specific file:

CONFIG_PATH=/etc/snip-sync/config.toml snip-sync serve

Configuration priority is environment variables, then the TOML file, then compiled defaults. The generated file contains the common settings:

An existing configuration file is fail-closed: malformed TOML or an unreadable file stops startup with an error naming the path. Defaults are used only when the configuration file is missing (and the normal bootstrap path may create it).

Environment variable overrides are strictly parsed: a present but invalid value (e.g., a non-numeric port) causes startup to fail with an error naming the variable and the supplied value. Boolean environment variables accept case-insensitive true, 1, yes, on and false, 0, no, off; unknown values fail instead of silently falling back. Range validation rejects operationally nonsensical values (e.g., zero ports, zero connection limits).

[server]
grpc_host = "127.0.0.1"
grpc_port = 50051
http_host = "127.0.0.1"
http_port = 50050

[server.database]
# path = "/var/lib/snip-sync/snippets.db"

[server.premade]
# directory = "/var/lib/snip-sync/premade-libraries"

[server.limits]
max_command_length = 1024
max_description_length = 1024
max_tags = 50
max_tag_length = 100
request_timeout_secs = 30

[server.rate_limit]
requests_per_minute = 120

[server.metrics]
# username = "metrics"
# password = "change-me"

[server.cors]
allowed_origins = ""

Important environment variables:

Variable Purpose
GRPC_HOST / GRPC_PORT gRPC bind address
HTTP_HOST / HTTP_PORT Health and metrics bind address
DATABASE_URL SQLite file path (not a remote database URL)
PREMADE_DIR Premade library directory
CONFIG_PATH Config file override
SNIP_SYNC_ALLOW_HTTP=true Explicit local plaintext mode (boolean: true/1/yes/on)
TLS_ENABLED=true Acknowledge TLS termination by a reverse proxy (boolean: true/1/yes/on)
METRICS_USERNAME / METRICS_PASSWORD Enable authenticated /metrics
CORS_ALLOWED_ORIGINS Comma-separated allowed origins
CORS_ALLOW_ALL=true Allow all CORS origins, development only (boolean: true/1/yes/on)

/health is unauthenticated and returns HTTP 200 only when the database is reachable. /metrics is disabled unless both metrics credentials are set.

Supervision fallback

croncheck is a lightweight fallback for hosts without systemd. It checks the actual /health response and starts one detached server when needed. For a production reverse-proxy deployment, use:

@reboot TLS_ENABLED=true /home/user/.cargo/bin/snip-sync croncheck
*/5 * * * * TLS_ENABLED=true /home/user/.cargo/bin/snip-sync croncheck

Prefer snip-sync startup install --method cron so these entries are idempotent and owned lines can be removed safely. SNIP_SYNC_ALLOW_HTTP=true is only generated for loopback binds; non-loopback startup requires the explicit TLS_ENABLED=true acknowledgement. croncheck is not a replacement for service logging, restart policies, or privilege management.

Other commands

snip-sync init                 # create config/layout and dev certs
snip-sync init --skip-cert    # create config/layout without OpenSSL
snip-sync init --force-cert   # regenerate the dev cert assets
snip-sync edit                # open the active config in $EDITOR (defaults to vim)
snip-sync stop                # stop the PID recorded by snip-sync
snip-sync restart             # manager-aware restart, or foreground serve
snip-sync startup instructions # print read-only startup instructions
snip-sync startup install     # install the detected startup manager
snip-sync startup uninstall   # remove only snip-sync-owned startup records
snip-sync update              # verified binary update, with exact Cargo fallback
snip-sync update --dry-run    # check version/asset/lifecycle without installing
snip-sync paths --json        # machine-readable path output
snip-sync completions bash    # generate shell completions

snip-sync cert uses the system openssl command. It refuses to overwrite existing assets unless --force is supplied and preserves existing assets if certificate generation fails.

snip-sync update selects the stable snip-sync version from crates.io and uses the exact matching, SHA-256-verified GitHub binary on supported hosts. Bootstrap, Cargo, and directly managed executables use the same path; source- only targets and a definite release-asset 404 use an exact-version Cargo fallback staged before replacement. Checksum, transport, and candidate identity failures are hard failures and never fall back to Cargo. A running server is restarted through its registered manager (or the direct lifecycle), while an intentionally stopped or inactive server remains stopped. If restart fails after replacement, the command reports the partial activation and the manual snip-sync restart recovery command.

Source build and Docker

For contributors building from the repository:

git clone https://github.com/eggstack/snip-it.git
cd snip-it/snip-sync
cargo build --release
../target/release/snip-sync --help

For a container image:

docker pull ghcr.io/eggstack/snip-it/snip-sync:latest

The container example exposes plaintext gRPC and should likewise be placed behind a TLS proxy before being exposed publicly. When the proxy runs on the host, bind the published ports to loopback:

docker volume create snip-sync-data
docker run -d \
  --name snip-sync \
  --restart unless-stopped \
  -p 127.0.0.1:50051:50051 \
  -p 127.0.0.1:50050:50050 \
  -v snip-sync-data:/data \
  -e DATABASE_URL=/data/snippets.db \
  -e GRPC_HOST=0.0.0.0 \
  -e HTTP_HOST=0.0.0.0 \
  -e TLS_ENABLED=true \
  -e SNIP_SYNC_ALLOW_HTTP=false \
  ghcr.io/eggstack/snip-it/snip-sync:latest

The repository's docker-compose.yml is useful for local/container-network deployments. Review its port bindings before using it on a remote host.

Troubleshooting

  • TLS termination is required: use SNIP_SYNC_ALLOW_HTTP=true only for a local direct connection, or put a TLS proxy in front and set TLS_ENABLED=true.
  • Client registration fails: use http://127.0.0.1:50051 for direct local serving and the proxy's https:// URL for production.
  • A second environment sees no libraries: it was probably registered as a new account. Provision the first environment's API key instead.
  • API key cannot be saved: configure a supported OS keychain. Snip-it refuses to write the API key as plaintext when the keychain is unavailable.
  • Port in use: run snip-sync paths and inspect the configured gRPC/HTTP ports.
  • Health check fails: request curl http://127.0.0.1:50050/health and inspect the server logs.
  • Server will not stop: use snip-sync stop --force only after confirming the PID with snip-sync paths and the process list.