---
asIndexPage: true
---

import { Steps, Callout, Cards } from "nextra/components";
import {
  IconPaint,
  IconLockOpen,
  IconKey,
  IconPlug,
  IconServer,
} from "@tabler/icons-react";

# Configuration

## Custom docker socket

Sometimes, there may be a need to specify a custom docker socket. Cup provides the `-s` option for this.

For example, if using Podman, you might do

```bash
$ cup -s /run/user/1000/podman/podman.sock check
```

This option is also available in the configuration file and it's best to put it there. If both are defined the CLI `-s` option takes precedence.

<Cards.Card
  icon={<IconPlug />}
  title="Custom Docker socket"
  href="/docs/configuration/socket"
/>

To disable Docker/Podman socket use "none" as value.

## Configuration file

Cup has an option to be configured from a configuration file named `cup.json`.

<Steps>
### Create the configuration file
Create a `cup.json` file somewhere on your system. For binary installs, a path like `~/.config/cup.json` is recommended.
If you're running with Docker, you can create a `cup.json` in the directory you're running Cup and mount it into the container. _In the next section you will need to use the path where you **mounted** the file_

### Configure Cup from the configuration file

Follow the guides below to customize your `cup.json`

<Cards>
  <Cards.Card
    icon={<IconKey />}
    title="Authentication"
    href="/docs/configuration/authentication"
  />
  <Cards.Card
    icon={<IconLockOpen />}
    title="Insecure registries"
    href="/docs/configuration/insecure-registries"
  />
  <Cards.Card
    icon={<IconPaint />}
    title="Theme"
    href="/docs/configuration/theme"
  />
  <Cards.Card
    icon={<IconServer />}
    title="Multiple servers"
    href="/docs/configuration/servers"
  />
</Cards>

Here's a full example:

```json
{
  "$schema": "https://raw.githubusercontent.com/sergi0g/cup/main/cup.schema.json",
  "version": 3,
  "images": {
    "exclude": ["ghcr.io/immich-app/immich-machine-learning"],
    "extra": ["ghcr.io/sergi0g/cup:v3.0.0"]
  },
  "registries": {
    "myregistry.com": {
      "authentication": "<YOUR_TOKEN_HERE>"
    }
  },
  "servers": {
    "Raspberry Pi": "https://server.local:8000"
  },
  "theme": "blue"
}
```

<Callout>
  If you want autocompletions and error checking for your editor, there is a
  JSON schema available. Use it by adding a `"$schema":
  "https://raw.githubusercontent.com/sergi0g/cup/main/cup.schema.json"` entry in
  your `cup.json` file.
</Callout>

### Run Cup with the new configuration file

To let Cup know that you'd like it to use a custom configuration file, you can use the `-c` flag, followed by the _absolute_ path of the file.

```bash
$ cup -c /home/sergio/.config/cup.json check
```

```bash
$ docker run -tv /var/run/docker.sock:/var/run/docker.sock -v /home/sergio/.config/cup.json:/config/cup.json ghcr.io/sergi0g/cup -c /config/cup.json serve
```

</Steps>

## Environment Variables

Want to make a quick change without editing your `config.json`? Cup also supports some configuration options from environment variables.
Here are the ones currently available:
- `CUP_AGENT` - Agent mode
- `CUP_IGNORE_UPDATE_TYPE` - Ignoring specific update types
- `CUP_REFRESH_INTERVAL` - Automatic refresh
- `CUP_SOCKET` - Socket
- `CUP_THEME` - Theme

Refer to the configuration page for more information on each of these.

Here's an example of a Docker Compose file using them:
```yaml
services:
  cup:
    image: ghcr.io/sergi0g/cup:latest
    command: serve
    ports:
      - 8000:8000
    environment:
      CUP_AGENT: "true"
      CUP_IGNORE_UPDATE_TYPE: major
      CUP_REFRESH_INTERVAL: "0 */30 * * * *"
      CUP_SOCKET: tcp://localhost:2375
      CUP_THEME: blue
```

<Callout>
    Heads up!
    Any configuration option you set with environment variables **always** overrides anything in your `cup.json`.
</Callout>