Install OpticWatch

Download OpticWatch, extract it and start it with one command. There is nothing to configure first.

This is the same on Windows, macOS and Linux once Docker is installed. Only extracting the download differs slightly, and the tabs below show each system. If you have not installed Docker yet, start with Install Docker.

1. Download OpticWatch

Free: download it from the Free download page. The current file is opticwatch-free-v1.1.1.tar.gz.
Pro or Integrator: use the download link in your purchase email. It works for 72 hours; after that, request a new one on the download page. Its name starts with opticwatch-pro or opticwatch-integrator; use it in place of the Free file name in the commands below.

The Free download page shows a SHA-256 checksum. To confirm the file arrived intact, compare it with the output of Get-FileHash opticwatch-free-v1.1.1.tar.gz in PowerShell, shasum -a 256 opticwatch-free-v1.1.1.tar.gz on macOS, or sha256sum opticwatch-free-v1.1.1.tar.gz on Linux.

2. Extract it and open a terminal in the folder

The download is a compressed archive. Extracting it creates a folder named like opticwatch-free-v1.1.1: this is the OpticWatch folder the rest of these guides refer to. Extracting it where you downloaded it is fine. Keep the folder afterwards, because you run commands from it to make backups and to update.

Windows 10 and 11 include the tar command. In PowerShell, go to the folder holding the download, extract it, and move into the new folder:

PowerShell

cd $HOME\Downloads
tar -xzf opticwatch-free-v1.1.1.tar.gz
cd opticwatch-free-v1.1.1

If you saved the file somewhere else, change the first line to that folder.

In Terminal, go to the folder holding the download, extract it, and move into the new folder:

Terminal

cd ~/Downloads
tar -xzf opticwatch-free-v1.1.1.tar.gz
cd opticwatch-free-v1.1.1

You can also double-click the file in Finder to extract it. Then, in Terminal, type cd (with a space), drag the new folder onto the Terminal window, and press Return.

If you downloaded the file on another computer, copy it to the server first, for example with scp. Then, on the server, extract it and move into the new folder:

Terminal

tar -xzf opticwatch-free-v1.1.1.tar.gz
cd opticwatch-free-v1.1.1

The folder contains docker-compose.yml, which describes how OpticWatch runs, a README.md with the full reference, and the OpticWatch program files. There is nothing to edit.

3. Start OpticWatch

Make sure Docker is running, then, in the same terminal, run:

Terminal or PowerShell

docker compose up -d

In plain terms: this reads docker-compose.yml in the current folder and starts OpticWatch in the background. The -d means “detached”, so your terminal is free again straight away, and closing the terminal does not stop OpticWatch.

The first start takes longer than later ones, because Docker:

downloads the public PostgreSQL, web server and Alpine Linux images that OpticWatch runs on;
packages the OpticWatch program from this folder into two small images on your computer (nothing is compiled, and no source code is involved);
creates OpticWatch's internal secrets, the database password and the key that encrypts your stored camera passwords, and keeps them for good. You never see or manage them.

4. Wait until it is healthy

Check on it with:

Terminal or PowerShell

docker compose ps

It lists one line per OpticWatch service. Repeat the command until the STATUS column of all three, postgres, api and web, ends in (healthy), for example Up 2 minutes (healthy). While a service is still starting it says (health: starting). This normally takes a minute or two after the downloads finish. A fourth service, init, runs once to create the secrets and then exits, so it may not be listed; that is expected.

5. Open OpticWatch in your browser

On the same computer, open http://localhost:38080.
From another computer on your network, open http://SERVER-IP:38080, replacing SERVER-IP with the address of the computer running OpticWatch, for example http://192.168.1.20:38080.

To find that address on the OpticWatch computer: on Windows, run ipconfig in PowerShell and use the IPv4 Address; on a Mac, open System Settings, then Network; on Linux, run hostname -I and use the first address. A server's address can change unless your network gives it a fixed one, so a reserved address in your router is worth setting up for a permanent installation.

If localhost works on the OpticWatch computer but another computer cannot connect, OpticWatch is running and something between them is blocking port 38080, most often the firewall on the OpticWatch computer. Allow incoming connections to port 38080 from your local network only. See Cannot open OpticWatch.

What is now running

Only the web interface is reachable from your network, on port 38080. The database and the OpticWatch API are reachable only by OpticWatch itself.
Your data is kept by Docker, not in the folder you extracted: cameras, sites, history and settings in one Docker volume and the internal secrets in another. Deleting the folder does not delete your data, but keep the folder anyway; you run commands from it.
It restarts on its own after a crash or a reboot and resumes monitoring. On Windows and macOS that needs Docker Desktop to be running, so set Docker Desktop to start when you sign in if OpticWatch should always be on.

Everyday commands

Run these in the OpticWatch folder. None of them deletes any data.

Terminal or PowerShell

docker compose ps                 # what is running, and its health
docker compose logs -f api        # follow the application log (Ctrl+C to stop)
docker compose restart            # restart everything
docker compose down               # stop everything; all data is kept
docker compose up -d              # start again