Install UsenetShare

Pick the row that describes you.

Whichever you choose, the app is one program that serves its own interface in your browser. Nothing else needs installing — the Usenet downloader, the poster and the web interface are all inside the download.

Currently published: Windows and Linux (and Docker). macOS builds are not being published at the moment.

Before you start

You need a Usenet provider account. UsenetShare is not a Usenet provider; it uses yours. If you do not have one, get one before setting up — the app has one-click presets for Newshosting and Tweaknews, and works with any provider that speaks NNTP over TLS.

You need a license key. There is no trial. The app will install and run without one, but publishing, importing, downloading and writing to disk are refused until a key is activated. Set up covers activation.

Roughly how much disk? The app itself is a few hundred megabytes. Beyond that, publishing uses a working cache with a budget you control (default ceiling 100 GB), and downloading needs room for what you download. The Storage page will model a download of a given size against your free space before you commit.

Windows

Install

1. Download UsenetShare-windows-x86_64-Setup.exe.

2. Run it. Windows will warn you that the publisher is unrecognised — see the SmartScreen warning below.

3. Three optional tick-boxes are offered:

   Option	Recommendation
   Create a desktop shortcut	Your preference
   Start Usenet Share automatically when I sign in to Windows	Tick it if you will publish or download anything large. Work resumes automatically when the app starts, so having it start with Windows means an interrupted transfer picks itself up.
   Allow Usenet Share in Windows Defender (recommended if downloads are blocked by antivirus)	Off by default and needs an administrator prompt. Tick it if downloads are slow or stall — see antivirus.

4. The app launches itself and opens your browser.

No administrator rights needed. It installs for your account only, into %LOCALAPPDATA%\Programs\UsenetShare. The one exception is the Defender option, which needs a prompt because it changes a machine-wide setting.

The SmartScreen warning

The installer is not yet code-signed, so Windows shows "Windows protected your PC". Choose More info → Run anyway.

This is worth being straight about: an unsigned installer is exactly what SmartScreen is designed to flag, and you should not take our word for it in general. Verify you downloaded from the official release page, and check the file size matches the release.

Antivirus can halve your speed

Real-time scanning inspects every file as it is written. A download that writes hundreds of megabytes a second gives a scanner a lot to chew on, and the effect is easily a 2× slowdown or stalls that look like network problems.

The installer's Defender option adds an exclusion for the app. If you use a different antivirus, exclude your download destination folder and the app's install folder there. The app detects likely interference and shows a banner if it sees the pattern.

Where it puts things

Your data folder holds the database, config.json, your license, your identity keys, the cache and the logs. The program folder is disposable; the data folder is not.

Linux

A self-contained archive. Extract and run — nothing is installed system-wide, no root required.

tar -xzf UsenetShare-linux-x86_64.tar.gz
cd UsenetShare
./UsenetShare

Your browser opens on http://127.0.0.1:8386/. If you are on a headless machine, see Linux server instead, or set USENET_NO_BROWSER=1 and open the address yourself.

Your data: ~/.local/share/usenetshare (or $XDG_DATA_HOME/usenetshare).

On a minimal install you may need libssl3 and zlib1g. Both are present on Ubuntu 22.04 and newer, and on any current desktop distribution.

Add it to your applications menu

Copy the supplied desktop entry and point it at where you extracted the archive:

cp installer/linux/usenet-share.desktop ~/.local/share/applications/
# then edit Exec= to the full path of the UsenetShare binary

Docker

For a NAS, unRAID, Synology, or any server you would rather manage as a container. Same build as the desktop app.

docker run -d --name usenetshare \
  -p 8386:8386 \
  -e PUID=1000 -e PGID=1000 -e TZ=Etc/UTC \
  -v /path/to/config:/config \
  -v /path/to/downloads:/downloads \
  --restart unless-stopped \
  ghcr.io/contemptx/usenetshare:latest

Then open http://<host>:8386.

Two things will bite you if you skip them:

/config must be persistent. Your license activation lives there, along with the database and the machine fingerprint. On a container with a throwaway /config, every restart looks like a new machine.

Set PUID/PGID to the user that owns your download folder. Run id to find yours. Get this wrong and downloads fail with permission errors that read like disk problems.

A login is required in Docker, unlike the desktop app: the first screen asks you to create an administrator account. Reaching the app over a network without one would leave it open to anyone who can route to the port.

Updates are done by pulling a new image, not from inside the app:

docker compose pull && docker compose up -d

Compose examples, and Portainer / unRAID / Synology specifics, are in ../../../installer/docker/README.md.

Currently amd64 only — the native downloader and encoder are x86_64 builds. That covers unRAID and Intel Synology and QNAP boxes, but not an ARM Raspberry Pi.

Linux server (systemd)

To have it run permanently on a headless box, under systemd, starting at boot:

tar -xzf UsenetShare-linux-x86_64.tar.gz
cd UsenetShare
sudo ./install.sh --admin-user admin --admin-pass '<a strong password>' \
                  --license-key '<your key>'

Supplying --admin-pass turns the login gate on, which you want on anything reachable over a network. Other flags: --port, --data-dir, --no-start.

Confirming it worked

Open http://127.0.0.1:8386/. You should get the Dashboard, with a blue banner inviting you to add your Usenet provider — that is expected on a fresh install and is the next guide.

If the page does not load:

Wait fifteen seconds and retry. The backend does startup work before serving, and the interface shows "System is starting up…" while it waits. On a large existing database this can take minutes.

Check the port. 8386 is the default. Something else may hold it; the app picks another and prints it to the console. Override with USENET_HTTP_PORT=9000.

Check nothing else is already running it. Starting a second copy against the same data folder is refused, deliberately.

Useful environment overrides

Rarely needed, occasionally essential.

If you set USENET_HTTP_HOST=0.0.0.0, set USENET_API_AUTH_ENABLE=1 too. The first makes the app reachable from your network; without the second, it is reachable by anyone on it.

Next

Set up — license, provider, identity. About five minutes.