snip-sync 0.1.2

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 binaries (skip either command if already installed).
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

In another terminal, register the client and sync:

snp register --server http://127.0.0.1:50051
snp sync --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 --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. 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.

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 run it under a supervisor:

# /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 --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).

[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
TLS_ENABLED=true Acknowledge TLS termination by a reverse proxy
METRICS_USERNAME / METRICS_PASSWORD Enable authenticated /metrics
CORS_ALLOWED_ORIGINS Comma-separated allowed origins
CORS_ALLOW_ALL=true Allow all CORS origins (development only)

/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 SNIP_SYNC_ALLOW_HTTP=false /home/user/.cargo/bin/snip-sync croncheck
*/5 * * * * TLS_ENABLED=true SNIP_SYNC_ALLOW_HTTP=false /home/user/.cargo/bin/snip-sync croncheck

Use systemd or another real supervisor for production. 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             # stop and run in the foreground
snip-sync update              # check crates.io and update Cargo installs
snip-sync update --dry-run    # check 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 is automatic for Cargo-managed installations. Homebrew, Docker, and source-built binaries should be updated through the tool that installed or built them.

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 an OS keychain. On a deliberately headless machine, SNP_ALLOW_PLAINTEXT_API_KEY=true snp register ... opts into plaintext storage and should be protected with strict file permissions.
  • 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.