# scalws-console

URL: https://scalws.com/docs/reference/programs/scalws-console/
Source: `docs/reference/programs/scalws-console.md` in the ScalWS repository

`scalws-console` is ScalWS Console, the web administration for scalws-controller: it talks to the controller over its local socket and edits the configuration through validated, audited changes.

```text
scalws-console <COMMAND>
```

Unix only; on other platforms it exits with `scalws-console runs on Linux only`. Every
command accepts `--help`; `scalws-console --version` prints the version. Day-to-day use is
described in [Console operations](https://scalws.com/docs/console/operations/).

## run

Serves the console over HTTPS. This is what `scalws-console.service` starts.

| Option | Default | Meaning |
|---|---|---|
| `--listen <ADDR>` | `0.0.0.0:8090` | HTTPS listen address. |
| `--state-dir <PATH>` | `/var/lib/scalws-console` | History, audit log and TLS material. Sessions are kept in memory. |
| `--credentials <PATH>` | `<state-dir>/credentials` | Accounts, one per line: `user:role:password` or `user:role:$argon2id$...` (mode 0600). The packaged unit passes `/etc/scalws/console/credentials`. |
| `--controller-config <PATH>` | `/etc/scalws/controller.yaml` | Gives the controller socket, the ScalWS configuration file and the instance limits. |
| `--controller-socket <PATH>` | from the controller configuration | Overrides [`controller.socket`](https://scalws.com/docs/reference/controller/#controller.socket). |
| `--scalws-config <PATH>` | from the controller configuration | Overrides [`controller.config`](https://scalws.com/docs/reference/controller/#controller.config), the ScalWS configuration that the console edits. |
| `--controller-log <PATH>` | none | Controller log file shown under Logs, in JSON lines. |
| `--tls-cert <PATH>`, `--tls-key <PATH>` | self-signed pair in the state directory | TLS certificate and key (PEM). Give both or neither. |
| `--tls-name <NAME>` | | Extra names or addresses for a generated self-signed certificate. Repeatable. |
| `--allow <CIDR\|ADDR>` | all | Client addresses allowed. Repeatable. |
| `--controller-binary <PATH>` | next to `scalws-console` | scalws-controller binary, used to validate `controller.yaml`. |
| `--webd-binary <PATH>` | next to `scalws-console` | scalwsd binary, used to check configuration drafts. |
| `--ctl-binary <PATH>` | next to `scalws-console` | scalwsctl binary, used to add and remove sites on the Domains page. |
| `--panel-status <PATH>` | `/var/lib/scalws-panel/status.json` | Status of the last panel sync (written by `scalwsctl panel sync`). |
| `--panel-state <PATH>` | `/var/lib/scalws-panel/state.json` | State file of panel mode; when it exists, a hosting panel manages the sites. |
| `--service-sandbox`, `--service-rw <PATH>` | off | Service sandbox for systems without systemd (see [sandbox](https://scalws.com/docs/guide/sandbox/)): writable are `/etc/scalws`, the state directory, `/srv/www`, `/home`, `/run/scalws-console`, `/tmp`, `/var/tmp`, `/dev/shm`, the device files `/dev/null`, `/dev/zero` and `/dev/full` (no other part of `/dev`, no `/proc`) and the `--service-rw` paths (a directory or a single file). |
| `--controller-restart-command <CMD>` | none | Restarts the controller after a `controller.yaml` change, for example `systemctl restart scalws-controller`. Without it, the change is written and waits for a restart. |
| `--session-idle-minutes <N>` | 30 | Session idle timeout. |
| `--health-timeout-secs <N>` | 120 | How long an apply waits for the controller to report the new generation healthy. |

`run` exits with 1 when the console cannot start.

## init-credentials

```text
scalws-console init-credentials [--credentials PATH] [--url URL]
```

Creates the credentials file (default `/etc/scalws/console/credentials`) with user `admin`
and a random password, unless the file exists; an existing file is left unchanged
(`<file> exists; left unchanged`). The password is not printed. The command shows how to
read it from the file, and `--url` adds the console address to the message:

```text
ScalWS Console administrator account created
  address:  https://<server-address>:8090
  user:     admin
  password: sudo grep '^admin:' /etc/scalws/console/credentials | cut -d: -f3
  file:     /etc/scalws/console/credentials (0600)
```

On Alpine the password line uses `doas` instead of `sudo`. The package runs this command on install when the file does not exist.

## hash-password

Reads a password from stdin and prints its argon2id hash for the credentials file:

```sh
echo 'new password' | scalws-console hash-password
```

## See also

* [Command-line programs](https://scalws.com/docs/guide/cli/)
* [scalwsctl](https://scalws.com/docs/reference/programs/scalwsctl/), [scalws-controller](https://scalws.com/docs/reference/programs/scalws-controller/), [scalwsd](https://scalws.com/docs/reference/programs/scalwsd/)
* [Console operations](https://scalws.com/docs/console/operations/), [Console security](https://scalws.com/docs/console/security/)