Installing SCVis

Download the latest SCVis release: scvis-docker (latest release)

SCVis runs in two Docker containers: one holds MySQL and the SCVis web application, the other holds the VACCS analyzer that executes your C programs. Each time they start, they fetch the current source from GitHub and build it, so you always run the latest version.

Apple Silicon Macs (M1 and later) run SCVis in a GitHub Codespace, and you need a free GitHub account.

The VACCS analyzer only works on Intel/AMD (x86_64) processors, and it cannot run under the Mac's Rosetta translation. On an Apple Silicon Mac the start script therefore runs SCVis on a GitHub cloud machine instead, and opens it in your browser. Intel Macs, Windows PCs and Linux PCs run SCVis on your own computer and need no GitHub account. To check which Mac you have, choose Apple menu > About This Mac: it lists either a Chip (Apple M1, M2, …) or a Processor (Intel). See Apple Silicon Macs: running in a Codespace below.

1. What you need

Intel Mac or Linux PC: nothing beyond a terminal. If Docker is missing, the start script offers to install it, and asks before changing anything on your system.
Windows PC: Git Bash, which comes with Git for Windows. Run every command below in Git Bash; the scripts do not run in Command Prompt or PowerShell. If Docker Desktop is missing, the start script offers to install it.
Apple Silicon Mac: a GitHub account and the GitHub CLI (gh). Docker is not needed on your Mac.
curl on your PATH. It ships with macOS, most Linux distributions and Git Bash.
An internet connection.

2. Unzip the download

The download is a zip file named scvis-docker-1.0.0.zip. Unzip it wherever you keep software:

macOS: double-click the zip in Finder.
Windows: right-click the zip and choose Extract All.
Linux or any terminal:

unzip scvis-docker-1.0.0.zip

This creates a folder named scvis-docker-1.0.0. Rename it to scvis-docker:

mv scvis-docker-1.0.0 scvis-docker

The folder name matters. Docker names the SCVis database after the folder, so a fixed name keeps your accounts and data when you upgrade to a newer release later.

3. Start SCVis

Apple Silicon Mac: do the one-time setup in running in a Codespace first.

Open a terminal in the folder and run the start script:

cd scvis-docker
scripts/run.sh

If you get Permission denied (common after extracting on Windows), run bash scripts/run.sh instead.

On your own computer, the script:

checks that Docker and Docker Compose are installed and running, and offers to install or start them if not;
picks a free port, starting at 8080;
builds and starts both containers (the first start is slow, because it compiles the analyzer from source);
waits for SCVis to respond;
opens SCVis in your web browser.

Log in with user admin and password admin1234. To use a different admin account, copy .env.example to .env and edit it before the first start; the admin account is created only once, when the database is new.

4. Stop SCVis

scripts/stop.sh              # stop, keep the database
scripts/stop.sh --wipe-db    # stop and delete the database

On an Apple Silicon Mac, stop the Codespace instead, as described below.

5. Upgrade to a new release

Stop SCVis with scripts/stop.sh.
Download and unzip the new release.
Replace the contents of your scvis-docker folder with the new files, keeping your .env file, and start SCVis again.

On an Apple Silicon Mac, the Codespace runs from your fork of scvis-docker. To upgrade it, open your fork on GitHub and click Sync fork, then run scripts/run.sh again.

Apple Silicon Macs: running in a Codespace

A GitHub Codespace is a cloud machine that GitHub runs for you. Codespaces always belong to a GitHub account, so you need one; a free personal account works.

Install the GitHub CLI from cli.github.com, or with Homebrew:
```
brew install gh
```
Tell the script which repository to use. A downloaded zip does not record where it came from, so in the scvis-docker folder run:
```
cp .env.example .env
echo "CODESPACE_REPO=stevenmcarr/scvis-docker" >> .env
```
Run scripts/run.sh. The first time, it walks you through these steps and asks before each one:
- signing in to GitHub, in your browser;
- granting the GitHub CLI permission to manage Codespaces;
- copying (forking) scvis-docker into your own GitHub account, because GitHub only creates a Codespace from a repository you can write to.
It then creates a 4-core Codespace, starts SCVis in it, and opens it in your browser at an address ending in .app.github.dev. The first start takes several minutes.

The SCVis address is private: it opens only in a browser where you are signed in to GitHub. Later runs of scripts/run.sh reuse the same Codespace.

Stopping: the script prints the exact command when SCVis starts. It looks like

gh codespace stop -c <codespace-name>

GitHub also stops an idle Codespace on its own after a while (30 minutes by default).

Usage limits: Codespace time comes out of the free monthly Codespaces allowance on your GitHub account, and a 4-core Codespace uses it four times as fast as the smallest machine. Stop the Codespace when you are done to make the allowance last. You can see your usage at github.com/settings/billing.

Optional: web mode

On your own computer, scripts/run.sh web serves SCVis over HTTPS with its own self-signed certificate, so your browser shows a certificate warning. The default mode uses plain HTTP and shows no warning. Web mode is not available in a Codespace.

Windows notes

If Docker Desktop is not installed, the start script offers to install it with winget. After it installs, log out and back in (or restart) if Windows asks you to, then run scripts/run.sh again.
Docker Desktop needs WSL2 enabled. If Docker Desktop does not finish starting, open it, complete any setup prompts, and run scripts/run.sh again.

Full technical details are in the scvis-docker repository.