# How to run a Sync Server ## ⚠️ This is intended for advanced Users _Running a server is an inherently technical process, if you have never run a server accessible on the internet, this is probably not for you._ ## Getting Started So you want to run an Instance of the Hammer Server? Great! There are two ways to run it: - **Docker** (easiest): a pre-built image that self-hosts with a single volume and no external database. See [Docker](#docker) below. - **Java executable**: download the distribution and run it directly on Windows, Linux, or macOS. Continue with the steps below. ## Docker A slim, non-root image is published to GitHub Container Registry, using the embedded PostgreSQL database by default: ```bash cd docker docker compose up -d ``` **See [HOW-TO-RUN-A-SERVER-DOCKER.md](HOW-TO-RUN-A-SERVER-DOCKER.md) for the full Docker guide.** The feature sections below (allowed users, email, community, analytics, encryption) apply to Docker too, since the server auto-loads `config.toml` from the mounted data directory. > The **networking** guidance below, in particular the `bindHosts` setting in > the reverse-proxy section, does **not** apply to containers, where it makes > the server unreachable. Follow the Docker guide instead for anything about > ports, binding, or TLS. ## Running the Java executable The Hammer server is a Java application that runs on Windows, Linux, and macOS. 1. Download the latest server release: - [ZIP](https://github.com/Darkrock-Studios/hammer-editor/releases/latest/download/server.zip) - [TAR](https://github.com/Darkrock-Studios/hammer-editor/releases/latest/download/server.tar) 2. Extract the archive to your desired location 3. Create your config file: `config.toml`. The server automatically loads a `config.toml` placed in its data directory (`~/hammer_data/`), so you don't need to pass `--config` if you put it there. To keep it elsewhere, pass its path with `--config` (see the platform-specific scripts below). It is strongly advised to use a port other than `80`, unless this is the only web-based program running on the system. If you intend to access the server by the host FQDN (e.g. `hammer.example.com`), make sure to set this in your DNS records; otherwise this will only be accessible via IP (e.g. `10.1.1.1`, `192.0.2.1`). ```toml host = "example.com" port = 80 ``` 4. Run the server (_see platform-specific instructions below_) 5. If everything worked, you should be able to access your server at your server's IP or at the host name you set in your config file and DNS configuration, such as: `http://example.com` 6. **Set up HTTPS before going any further.** Clients only speak `https` and will not connect to a plain HTTP server, so it needs either its own certificate or a reverse proxy holding one. See [Setting up SSL](#setting-up-ssl-required-for-direct-connections). 7. **IMPORTANT!** You must now download one of the clients and create an account on the server. The first account created will be the admin account. ## Network binding By default the server binds to all IPv4 interfaces (`0.0.0.0`), so it accepts connections from the network. To isolate it (for example when a reverse proxy on the same host is the only thing that should reach it) restrict the bind to loopback with `bindHosts`: ```toml # Accept loopback connections only (IPv4 and IPv6). Default is ["0.0.0.0"]. bindHosts = ["127.0.0.1", "::1"] ``` `bindHosts` is the network interface(s) to listen on, and is distinct from `host`, which is the public name shown to users. Each address gets its own listener (and its own HTTPS listener when an SSL cert is configured). ## Time zone The server stamps timestamps in the host's time zone, which on most containers and fresh installs is UTC. To use your local zone instead, set `timezone` to an IANA zone ID ([full list of accepted IDs](SERVER-TIMEZONES.md)): ```toml timezone = "Europe/Paris" ``` Two environment variables do the same thing, for setups where the config file is inconvenient: `HAMMER_TIMEZONE`, and the standard `TZ`. `config.toml` wins over `HAMMER_TIMEZONE`, which wins over `TZ`. ```sh HAMMER_TIMEZONE=Europe/Paris ./run.sh ``` The zone is applied at startup, and logged as `Server time zone: ...` so you can confirm it took. An unknown ID in `timezone` or `HAMMER_TIMEZONE` aborts startup rather than quietly leaving every timestamp in the wrong zone. `TZ` is treated more leniently, because the POSIX form some systems use (`CET-1CEST,M3.5.0`) is a legitimate value the operating system has already acted on: a `TZ` Hammer cannot read logs a warning and leaves the zone to the host. What it affects: - Dates and times on the web pages the server renders: the dashboard, admin screens, monitoring, editorial reviews, and published story dates. - Log line timestamps, both in the console output and the admin log viewer. What it does not affect: - Stored data. Everything is persisted as an absolute instant (UTC in the database), so changing the zone re-renders existing timestamps rather than shifting any data. - The desktop, Android, and iOS clients. Those render in each device's own zone. - Maintenance job scheduling. Jobs run on fixed intervals from server start, not at a wall-clock time of day, so no schedule moves with the zone. One caveat when changing the zone on a server that has already been running: date-only admin fields are interpreted in whatever zone was in effect when they were saved. An Allowed Users expiry entered as "expires Sep 1" is stored as the end of Sep 1 in the old zone, so afterwards the edit form can show the neighboring date, and re-saving that row moves the expiry by a day. Nothing expires early or late on its own; only re-saving an existing row does it. Note that `TZ` alone already works on Linux, because the JVM reads it. Hammer reads it back explicitly so the same variable also works on Windows and macOS hosts, which ignore it. ## Rich link previews (optional) By default, sharing an author or story link on social media shows a branded static preview card. To instead generate a **per-page** share image (the story title or author name rendered onto the card) enable `richLinkPreviews`: ```toml richLinkPreviews = true ``` Generated images are disk-cached and pruned automatically; see [Disk cache](#disk-cache) for where they live and how to move them. **Requirement:** rendering the text uses headless AWT, which needs native font libraries installed. On Debian/Ubuntu: ```sh sudo apt-get install -y fontconfig libfreetype6 ``` Without them, leave `richLinkPreviews` off (the default): link previews still work via the static cards, so the out-of-the-box setup needs nothing extra. ## Storage The server persists its data in a PostgreSQL database. It supports two modes: - **Embedded (default):** An in-process PostgreSQL server is started automatically. Data lives under `~/hammer_data/pgdata/`. No external services required: drop the JAR on a box and run it. - **Remote:** Point at an externally-managed PostgreSQL server. Use this when you outgrow embedded or want managed backups. Embedded is the default; no config is needed for it. This is the intended mode for self-hosters. To override the embedded port, or to switch to remote, add a `[storage]` block to `config.toml`: ```toml # Embedded (defaults shown). Omit this whole block to accept the defaults. [storage] type = "embedded" [storage.embedded] port = 54329 # pinned for predictability dataDirName = "pgdata" ``` ```toml # Remote. [storage] type = "remote" [storage.remote] host = "db.example.com" port = 5432 database = "hammer" user = "hammer" password = "..." schema = "public" poolSize = 10 useSsl = true ``` ### Upgrading from a pre-PostgreSQL version Older releases (prior to v3.1.0) used SQLite (`~/hammer_data/server.db`). The first run after upgrading auto-detects the file and migrates its contents into PostgreSQL inside a single transaction, then renames the source to `server.db.migrated-.bak`. If migration fails for any reason, the SQLite file is left untouched and the server exits with an error. Fix the cause and start again. To rehearse the migration against a copy of production before flipping the live config, run with `--migrate-dry-run`: it does everything except commit and rename. ## Disk cache The server caches two regenerable things on disk: rendered story HTML and the OpenGraph share images used for rich link previews. By default they live in `~/hammer_data/cache/`, one subdirectory per cache. Nothing in there is durable data (deleting it costs a re-render, never content) so it is a good candidate for a scratch volume: ```toml [cache] # Defaults shown. Omit this whole block to accept them. directory = "/var/tmp/hammer-cache" # default: /cache maxSizeMb = 200 # per cache, oldest entries evicted first (max 1048576) ``` A relative `directory` is resolved against the config file's own directory. The path must be creatable and writable at startup, or the server aborts rather than silently running with the caches disabled. Only publicly readable stories are ever written to the HTML cache, so a password-protected story's prose never lands on the cache volume. ## Account deletion retention Users can delete their own account from the web dashboard. A deleted account is locked out immediately (no login, no sync, everything unpublished, pen name released), but its data is retained on the server for a grace window so you can restore it from **Admin → Users** if the user changes their mind. A daily job permanently deletes accounts once the window elapses. ```toml [accountDeletion] # Defaults shown. Omit this whole block to accept them. retentionDays = 30 # days before a deleted account is purged for good (1 to 3650) ``` The window is evaluated against each account's deletion time on every job run, so lowering the value also purges accounts that are already past the new, shorter window. ## Encryption at rest Content encryption at rest is **optional**: a fresh server stores in plaintext and needs no key material. This is recommended for most self-hosters. Encryption is slower, and carries the possibility of total data loss if key material is mishandled. If you want to enable at-rest encryption, see [Encryption at rest & key management](SERVER-SECRET-STORAGE.md) for the full walkthrough. ## Platform-Specific Instructions ### Linux Create a script to run the server in the top level of the installation directory (e.g. `hammer/`): `run.sh` ```bash #!/bin/bash ./bin/server --config config.toml ``` Make the script executable: ```bash chmod +x run.sh ``` Run the server: ```bash ./run.sh ``` (Optional) To set up the server to run automatically, configure a systemd service. #### SystemD Service Example You will want to create a system user without login ability for security purposes. ``` sudo adduser hammer --disabled-login ``` And then make sure to change ownership for the installation directory to the new user. ``` sudo chown -R hammer:hammer hammer/ ``` Finally, create the `hammer.service` file in your `systemd/system` folder. Be sure to change the `[installation directory]` to your directory. ``` [Unit] Description=Hammer Server for Story Editing After=network.target postgresql.service [Service] User=hammer Group=hammer Type=simple WorkingDirectory=[installation directory] ExecStart=[installation directory]/run.sh Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target ``` ### Windows Create a script to run the server in the top level of the installation directory (e.g. `hammer\`): `run.bat` ```batch @echo off bin\server.bat --config config.toml ``` Run the server: ```batch run.bat ``` ### macOS Create a script to run the server in the top level of the installation directory (e.g. `hammer/`): `run.sh` ```bash #!/bin/bash ./bin/server --config config.toml ``` Make the script executable: ```bash chmod +x run.sh ``` Run the server: ```bash ./run.sh ``` ## Setting up SSL (required for direct connections) **Hammer clients only speak `https`.** A client will never connect over plain HTTP, so a server that clients reach **directly** must terminate TLS. The only deployment that can run Hammer on plain HTTP is one sitting **behind a reverse proxy**: the proxy holds the certificate and forwards plain HTTP to Hammer on the same host. There are two ways to serve Hammer over `https`. Pick **one**: - **Java SSL (this section):** Hammer terminates TLS itself, reading your certificate directly. Simplest if Hammer is the only thing on the box. - **Reverse proxy:** A proxy such as Nginx terminates TLS and forwards plain HTTP to Hammer. Preferred if you run other services on the same host. If you go this route, **skip the rest of this section** and follow [Reverse Proxy using Nginx](#reverse-proxy-using-nginx) instead. > The plain HTTP connector (`port`, default 8080) still exists solely for the reverse-proxy > case. Do not expose it directly to clients; they won't use it. If you want Hammer to terminate SSL itself, you'll first need to edit your server config file and add these lines: ```toml sslPort = 443 forceHttps = true # Optional, defualts to true ``` ### Getting an SSL Certificate #### Self-signed certs are not supported in production Don't use a self-signed certificate for a real deployment. The mobile clients trust only the system CA store (Android won't trust user-added or self-signed CAs by default, and iOS rejects them too) so they'll fail the TLS handshake with no way to override it. The desktop client also rejects self-signed certs outside development mode. Use a real certificate from **Let's Encrypt** below (or put Hammer behind a reverse proxy that holds one). #### Development: automatic self-signed cert When you run the server with `--dev` and **no** `sslCert` configured, Hammer generates a self-signed certificate on first boot and serves it, persisting the keystore to `hammer_data/dev-selfsigned.jks` so it stays stable across restarts. To avoid the privileged port 443 (which needs root on Linux/macOS), the dev connector listens on **8443** by default; set `sslPort` to override. Point the client at `localhost:8443` or `127.0.0.1:8443`. The desktop client run with `--dev` trusts this self-signed cert, but **only for loopback hosts** (localhost / 127.0.0.1): a `--dev` client talking to any other host still does full certificate and hostname validation, so pointing a dev build at a real server is not silently insecure. This path never activates without `--dev`; a production server with no `sslCert` serves plain HTTP only (for the reverse-proxy case). Mobile clients still won't trust the self-signed cert, so develop the mobile clients against a real certificate or a reverse proxy. #### Let's Encrypt The most common way to get a properly signed certificate is from **Lets Encrypt!** It's free and [relatively easy to setup](https://letsencrypt.org/getting-started/). Hammer can accept certificates in two formats: - PEM - _Privacy Enhanced Mail_ (recommended; what certbot/Let's Encrypt produces directly) - JKS - _Java Key Store_ (legacy) #### PEM (recommended) Once you've set it up, Let's Encrypt will give you a directory of PEM files such as `/etc/letsencrypt/live/example.com`. The two files we care about are `fullchain.pem` and `privkey.pem`. Point **Hammer** straight at them in your `config.toml`, no conversion needed: ```toml [sslCert] certChainPath = "/etc/letsencrypt/live/example.com/fullchain.pem" privateKeyPath = "/etc/letsencrypt/live/example.com/privkey.pem" ``` #### JKS (legacy) Hammer also accepts a Java Key Store. You can convert the PEM files above into a `cert.jks` with this script: `convert.sh` ```shell #!/bin/sh openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out certificate.p12 -name "certificate" keytool -importkeystore -srckeystore certificate.p12 -srcstoretype pkcs12 -destkeystore cert.jks ``` Once you provide a password it will produce `cert.jks`. Point **Hammer** at it: ```toml [sslCert] path = "/etc/letsencrypt/live/example.com/cert.jks" storePassword = "1234567890" keyPassword = "1234567890" keyAlias = "certificate" ``` ### Renewing your SSL cert This applies to the **Java SSL** method, where Hammer terminates TLS and holds the HTTP port. If you run behind a reverse proxy, the proxy owns ports 80/443 and renews its certificate without ever touching Hammer, so none of the stop/start dance below is needed. `certbot renew` renews the certificate in place, rewriting `fullchain.pem` and `privkey.pem`. Two things to know: - Because **Hammer** holds the HTTP port, certbot's standalone challenge needs that port free, so Hammer must be stopped while certbot runs. - A running server reads its certificate only at startup, so it won't pick up a renewed cert until it restarts. Configure both as certbot renewal hooks so the renewal that runs automatically handles everything. Add them to the cert's renewal config, `/etc/letsencrypt/renewal/.conf`, under the `[renewalparams]` section: ```ini pre_hook = systemctl stop hammer post_hook = systemctl start hammer ``` These hooks run **only** when a renewal actually happens, not on the routine no-op checks, so Hammer is stopped only when a new cert is genuinely being issued. > **Note:** You can also pass `--pre-hook`/`--post-hook` on the command line, but certbot only > persists them into the > config when a renewal actually occurs, so setting them while no renewal is due (the common case) > silently does > nothing. Editing the config directly, as above, always works. When Hammer points at the PEM files directly (recommended), the `post_hook` restart is all that's needed to pick up the new cert; there's no conversion step. Renewals fire automatically on a timer that certbot installs. Confirm it's active: ```shell systemctl list-timers | grep certbot ``` The timer's unit name depends on how certbot was installed, either `certbot.timer` (apt/dnf) or `snap.certbot.renew.timer` (snap), which is why grepping `list-timers` is the reliable check. ## Reverse Proxy using Nginx Instead of having Hammer terminate TLS itself (the [Setting up SSL](#setting-up-ssl-optional) section above), you can put it behind a reverse proxy that terminates TLS and forwards plain HTTP to Hammer. This is good practice, especially when other services share the host, and is documented here for Nginx. Use **either** this approach **or** Java SSL, not both. ### Changes to config.toml Example port used. (If you're running multiple services on a webserver, you've probably already used 8080.) For security purposes, make sure to set `bindHosts` as below (V => 3.4.0). ```toml port = 8200 bindHosts = ["127.0.0.1", "::1"] ``` Make sure to update your DNS with your desired URL to be able to use LetsEncrypt and the like. ### Behind a proxy, every request looks like it came from the proxy If nothing proxies your server, skip this section: Hammer already sees each visitor's real address, and nothing needs configuring. Behind a proxy it sees the proxy instead, identically for every visitor. That breaks three things: the login rate limiter (10 attempts per minute) becomes one bucket shared by the whole server rather than one per client, so a burst from anywhere locks everyone out; recorded login IPs all read as the proxy; and public story reader counts collapse to a single visitor. Your proxy already sends the real values in `X-Forwarded-For` and `X-Forwarded-Proto` (both are in the Nginx config below). Tell Hammer to trust them: ```toml # Default false. Only enable when clients cannot reach the server directly. trustProxyForwarding = true ``` > [!WARNING] > Only set this when the proxy is the *only* route to the server, which is what > `bindHosts = ["127.0.0.1", "::1"]` above ensures. `X-Forwarded-For` is just a request header: > anything that can reach Hammer directly can forge one, and with this on that means a fresh > identity per request and a free pass through the login rate limiter. If your server is > reachable both through the proxy and directly, leave it `false`. **One proxy only.** Hammer trusts the last `X-Forwarded-For` entry, which is the one your proxy added. Put a CDN in front of Nginx (Cloudflare, Fastly) and that entry becomes the CDN's edge node rather than the visitor, so have Nginx replace the header with the address the CDN reports: ```nginx # Cloudflare example. Keep set_real_ip_from restricted to the CDN's ranges, # or anything can supply its own CF-Connecting-IP. set_real_ip_from 173.245.48.0/20; # ...and the rest of Cloudflare's published ranges real_ip_header CF-Connecting-IP; proxy_set_header X-Forwarded-For $remote_addr; ``` ### Base Nginx Config Create your base file. Make sure to change `hammer.example.com` to your domain! `nano /etc/nginx/sites-available/hammer` ```nginx server { listen 80; server_name hammer.example.com; location / { proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://localhost:8200; } } ``` ### HTTPS See LetsEncrypt or your favorite SSL provider for an SSL certificate. Once that is completed, install said new cert into your Nginx file. Be sure to set the proper path for your certificate fullchain and private key. Once again, make sure to change `hammer.example.com` to your domain in the `server_name` lines and the `ssl_certificate*` lines. If LetsEncrypt installs the HTTP to HTTPS redirect itself, make sure your file roughly reflects this example below. ```nginx server { listen 80; server_name hammer.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305; ssl_session_cache shared:SSL:10m; ssl_session_timeout 1d; add_header X-Frame-Options "SAMEORIGIN" always; add_header X-Content-Type-Options "nosniff" always; add_header 'Referrer-Policy' 'same-origin'; ssl_certificate /etc/letsencrypt/live/hammer.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/hammer.example.com/privkey.pem; server_name hammer.example.com; location / { proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://localhost:8200; } } ``` ### Link, Test, Reload Link the file to the `sites-enabled` folder. ```sh ln -s /etc/nginx/sites-available/hammer /etc/nginx/sites-enabled ``` Make sure to test your configuration! ```sh sudo nginx -t ``` As long as that doesn't throw any errors, you can restart nginx. You should now be able to access your Hammer server web page at your URL! ## Allowed Users Account creation is restricted to allowed email addresses. This is always on and cannot be disabled; it is the nominal state of a Hammer server, since there are no moderation tools or account verification, and a fully open server would fill with spam very quickly. To allow someone to use your server, go to `/admin/allowed-users` on the website (logged in as your admin account) and add their email address. They can then create their own account on the `/signup` page, or from within the Hammer app. Entries can carry an optional expiry date, after which the user's access is revoked automatically. When upgrading a server that had explicitly **disabled** the old whitelist, every existing account is added to the allowed users list automatically on first startup (with the reason "Existing account"), so nobody is locked out by the upgrade. Servers that were already enforcing the whitelist are left untouched: entries that were removed or expired stay revoked. ## Enable Community By default this is disabled. To enable it, add this line to your server config: ```toml communityEnabled = true ``` This will enable several new pages on the website found at: `/community` Users will now be able to opt-in to the community if they have already selected a **Pen Name**. ## Setup Email Sending (_Optional_) Currently, we mainly use Email for password reset. Eventually we maybe have account verification, and potentially other things we send emails for. There are several supported ways to send emails: - SMTP - Standard Email - Mailgun - https://www.mailgun.com/ - Sendgrid - https://sendgrid.com - Postmark - https://postmarkapp.com/ You can configure the email provider by first selecting which you want to use in your `config.toml` file: ```toml emailProvider = "SMTP" ``` Then restart your server and navigate to the admin page to configure your email settings. Only SMTP has been thoroughly tested so far. ## Web Analytics (_Optional_) You can opt into a web analytics provider to measure traffic to your server's public web pages. Analytics is only served on **public (logged-out) pages**. It is never injected into the dashboard, story, or admin pages of signed-in users. By default analytics is disabled (`type = "none"`). Supported providers are [Umami](https://umami.is) and [Google Analytics](https://analytics.google.com). Both providers report a `download` event, broken down by `platform` and `format`, when a visitor clicks a download button on the home page. ### Umami Create a website in your Umami dashboard, copy its **Website ID**, and add: ```toml [analytics] type = "umami" [analytics.umami] websiteId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # scriptUrl defaults to Umami Cloud. To use a self-hosted Umami instance, # point it at your own script, e.g.: scriptUrl = "https://umami.example.com/script.js" # connectSrc overrides the CSP connect-src event hosts. Umami Cloud's script # POSTs events to a gateway origin that has moved several times; if tracking # is blocked by CSP after a host change, set the current host(s) here to fix # it without a code release, e.g.: connectSrc = ["https://gateway.umami.is"] ``` ### Google Analytics Create a GA4 property, copy its **Measurement ID** (`G-XXXXXXXXXX`) from the data stream, and add: ```toml [analytics] type = "google" [analytics.google] measurementId = "G-XXXXXXXXXX" ``` The `platform` and `format` event parameters are sent automatically, but GA4 only shows them in reports once you register them as **custom dimensions** in the GA admin console. The configuration is designed to grow: support for additional providers can be added under the `[analytics]` section in the future by selecting a different `type`.