# Running Pupcloud

Pupcloud is distributed as a single executable file. [Download and unpack the proper file for your OS/arch](https://germ.gitbook.io/pupcloud/installation-and-building#installation).

Once done, just execute it with the directory to serve as an argument:

```bash
pupcloud -r /my/dir
```

Then, open `http://localhost:17178` with a browser. As simple as that!

Run`pupcloud --help` to see the other configuration options:

```
Pupcloud v0.8.0 (c) 2022 Germano Rizzo
Usage of ./pupcloud:
  -E, --allow-edits                 Allows changes to FS (default: don't)
      --allow-root                  Allow launching as root (default: don't)
      --bind-to string              The address to bind to (default "0.0.0.0")
      --follow-symlinks             Follow symlinks when traversing directories (default: don't)
      --max-upload-size int         The max size of an upload, in MiB (default 32)
  -P, --password string             The main access password, if desired. Use --pwd-hash for a safer alternative
  -p, --port int                    The port to run on (default 17178)
  -H, --pwd-hash string             SHA256 hash of the main access password, if desired
  -r, --root string                 The document root to serve
      --share-port int              The port of the sharing interface (default 17179)
      --share-prefix string         The base URL of the sharing interface (default: 'http://localhost:' + the port)
      --share-profile stringArray   Profile for sharing, in the form name:secret, multiple profiles allowed
      --share-profiles string       Profiles for sharing, in the form name:secret, multiple profiles comma-separated
      --title string                Title of the window (default "🐶 Pupcloud")
```

* enable "write" operations (delete/cut/paste/upload...;`-E` or `--allow-edits`);
* setup [authentication ](https://germ.gitbook.io/pupcloud/guides/authentication)(`-P` or `-H`);
* setup [folder sharing](https://germ.gitbook.io/pupcloud/guides/sharing-a-folder) (`--share-profile`/`--share-profiles`, `--share-port`, `--share-prefix`)
* specify a title/header for the web UI page (`--title`);
* use a different port then the default of 17178 (`-p`);
* bind to a network interface (`--bind-to`);
* instruct pupcloud to follow symlinks (`--follow-symlinks`);
* specify a maximum size for upload, in Megabytes (`--max-upload-size`).

By default, it's forbidden to run it as root. Use `--allow-root` if you (really) want to.

### Configure by env vars

Every CLI parameter can be specified via environment variable. If the corresponding env var is specified, it overwrites a CLI parameter. This is useful e.g. in Docker.

Env vars are mapped to CLI params as such:

| CLI Parameter         | Environment Variable  | Example                                   |
| --------------------- | --------------------- | ----------------------------------------- |
| `--root`, `-r`        | `PUP_ROOT`            | `PUP_ROOT=./`                             |
| `--bind-to`           | `PUP_BIND_TO`         | `PUP_BIND_TO=192.168.1.0`                 |
| `--port`, `-p`        | `PUP_PORT`            | `PUP_PORT=8080`                           |
| `--title`             | `PUP_TITLE`           | `PUP_TITLE=WowSite`                       |
| `--password`, `-P`    | `PUP_PASSWORD`        | `PUP_PASSWORD=ciao`                       |
| `--pwd-hash`, `-H`    | `PUP_PWD_HASH`        | `PUP_PWD_HASH=5302bf`                     |
| `--allow-edits`, `-E` | `PUP_ALLOW_EDITS`     | `PUP_ALLOW_EDITS=1`                       |
| `--share-profile`     | *nothing*             |                                           |
| `--share-profiles`    | `PUP_SHARE_PROFILES`  | `PUP_SHARE_PROFILES=k1:v1,k2:v2`          |
| `--share-prefix`      | `PUP_SHARE_PREFIX`    | `PUP_SHARE_PREFIX=http://localhost:12345` |
| `--share-port`        | `PUP_SHARE_PORT`      | `PUP_SHARE_PORT=12345`                    |
| `--max-upload-size`   | `PUP_MAX_UPLOAD_SIZE` | `PUP_MAX_UPLOAD_SIZE=64`                  |
| `--allow-root`        | `PUP_ALLOW_ROOT`      | `PUP_ALLOW_ROOT=1`                        |
| `--follow-symlinks`   | `PUP_FOLLOW_SYMLINKS` | `PUP_FOLLOW_SYMLINKS=1`                   |

{% hint style="warning" %}
The boolean env vars (`PUP_ALLOW_EDITS`, `PUP_ALLOW_ROOT`, `PUP_FOLLOW_SYMLINKS`) are considered only when they are enabled, i.e. set to `1`. They cannot be used to deactivate a CLI parameter.
{% endhint %}

### Write a "config file"

Pupcloud can't be configured with a config file. It's an explicit design choice, I wanted to limit all the "cruft" normally involved in installing an application... to the extreme. One day this might change though (see [Discussion #26](https://github.com/proofrock/pupcloud/discussions/26) for a short discussion).

For now, what *can* be done is to use the env vars to build a shell script that looks like a config file; something like:

```bash
#!/bin/bash
export PUP_ROOT=/my/root
export PUP_ALLOW_EDITS=1
export PUP_PASSWORD=ciao
./pupcloud
```

or inline:

```bash
#!/bin/bash
PUP_ROOT=/my/root \
PUP_ALLOW_EDITS=1 \
PUP_PASSWORD=ciao \
./pupcloud
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://germ.gitbook.io/pupcloud/guides/running-pupcloud.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.