cobalt

how to run a cobalt instance

using docker compose and package from github (recommended)

to run the cobalt docker package, you need to have docker and docker-compose installed and configured.

if you need help with installing docker, follow only the first step of these tutorials by digitalocean:

how to run a cobalt docker package:

create a folder for cobalt config file, something like this:
```
 mkdir cobalt
```
go to cobalt folder, and create a docker compose config file:
```
 cd cobalt && nano docker-compose.yml
```
i’m using nano in this example, it may not be available in your distro. you can use any other text editor.
copy and paste the sample config from here for either web or api instance (or both, if you wish) and edit it to your needs. make sure to replace default URLs with your own or cobalt won’t work correctly.
finally, start the cobalt container (from cobalt directory):
```
 docker compose up -d
```

if you want your instance to support services that require authentication to view public content, create cookies.json file in the same directory as docker-compose.yml. example cookies file can be found here.

cobalt package will update automatically thanks to watchtower.

it’s highly recommended to use a reverse proxy (such as nginx) if you want your instance to face the public internet. look up tutorials online.

run cobalt api outside of docker (useful for local development)

requirements:

node.js >= 18
git
pnpm

clone the repo: git clone https://github.com/imputnet/cobalt.
go to api/src directory: cd cobalt/api/src.
install dependencies: pnpm install.
create .env file in the same directory.
add needed environment variables to .env file. only API_URL is required to run cobalt.
- if you don’t know what api url to use for local development, use http://localhost:9000/.
run cobalt: pnpm start.

ubuntu 22.04 workaround

nscd needs to be installed and running so that the ffmpeg-static binary can resolve DNS (#101):

sudo apt install nscd
sudo service nscd start

list of environment variables for api

* the higher the nice value, the lower the priority. read more here.

** in order to enable turnstile bot protection, all three TURNSTILE_SITEKEY, TURNSTILE_SECRET and JWT_SECRET need to be set.

FREEBIND_CIDR

setting a FREEBIND_CIDR allows cobalt to pick a random IP for every download and use it for all requests it makes for that particular download. to use freebind in cobalt, you need to follow its setup instructions first. if you configure this option while running cobalt in a docker container, you also need to set the API_LISTEN_ADDRESS env to 127.0.0.1, and set network_mode for the container to host.

api key file format

the file is a JSON-serialized object with the following structure:

type KeyFileContents = Record<
    UUIDv4String,
    {
        name?: string,
        limit?: number | "unlimited",
        ips?: (CIDRString | IPString)[],
        userAgents?: string[]
    }
>;

where UUIDv4String is a stringified version of a UUIDv4 identifier.

name is a field for your own reference, it is not used by cobalt anywhere.
limit specifies how many requests the API key can make during the window specified in the RATELIMIT_WINDOW env.
- when omitted, the limit specified in RATELIMIT_MAX will be used.
- it can be also set to "unlimited", in which case the API key bypasses all rate limits.
ips contains an array of allowlisted IP ranges, which can be specified both as individual ips or CIDR ranges (e.g. ["192.168.42.69", "2001:db8::48", "10.0.0.0/8", "fe80::/10"]).
- when specified, only requests from these ip ranges can use the specified api key.
- when omitted, any IP can be used to make requests with that API key.
userAgents contains an array of allowed user agents, with support for wildcards (e.g. ["cobaltbot/1.0", "Mozilla/5.0 * Chrome/*"]).
- when specified, requests with a user-agent that does not appear in this array will be rejected.
- when omitted, any user agent can be specified to make requests with that API key.
if both ips and userAgents are set, the tokens will be limited by both parameters.
if cobalt detects any problem with your key file, it will be ignored and a warning will be printed to the console.

an example key file could look like this:

{
    "b5c7160a-b655-4c7a-b500-de839f094550": {
        "limit": 10,
        "ips": ["10.0.0.0/8", "192.168.42.42"],
        "userAgents": ["*Chrome*"]
    },
    "b00b1234-a3e5-99b1-c6d1-dba4512ae190": {
        "limit": "unlimited",
        "ips": ["192.168.1.2"],
        "userAgents": ["cobaltbot/1.0"]
    }
}

if you are configuring a key file, do not use the UUID from the example but instead generate your own. you can do this by running the following command if you have node.js installed: node -e "console.log(crypto.randomUUID())"

This site is open source. Improve this page.