# Debian, raw and curl

> Install from a signed apt repository and download plain files from Telesphorepo, and what is different when you publish them with the CLI or curl.

Source: https://docs.telesphorepo.com/debian-and-raw/

This page sets up apt and curl to install and download from Telesphorepo. To publish packages and files, see [Publish from a project](/publish-from-a-project/), under Publish your packages; what is different for Debian and raw files is under [Publish Debian packages and raw files](#publish-debian-packages-and-raw-files).

An admin first makes the repository: **Settings** › **Repositories** › **New repository**, with the format **Debian (apt)** or **Raw files**.

## Install from a Debian repository

The examples use a Debian repository named `apt`.

1. On each machine that installs, add the key and the source:

   ```sh
   sudo mkdir -p /etc/apt/keyrings
   sudo curl -fsSL https://repo.example.com/debian/apt/key.asc -o /etc/apt/keyrings/telesphorepo.asc
   echo "deb [signed-by=/etc/apt/keyrings/telesphorepo.asc] https://repo.example.com/debian/apt stable main" \
     | sudo tee /etc/apt/sources.list.d/telesphorepo.list
   ```

2. Install:

   ```sh
   sudo apt update
   sudo apt install my-package
   ```

Private Debian repository

apt needs your username and a read token. Create the token under **Settings** › **Tokens** › **New read token**. It starts with `trp_`. Each command below asks for the token at a hidden prompt.

Download the key with the token:

```sh
printf 'Read token: '; read -rs READ_TOKEN; echo
printf 'user = "YOUR_USERNAME:%s"\n' "$READ_TOKEN" \
  | sudo curl -fsSL -K - https://repo.example.com/debian/apt/key.asc -o /etc/apt/keyrings/telesphorepo.asc
```

Give apt the token. The `install` command makes the file readable by root only before the token goes in. `tee` writes to the file only, not to the terminal.

```sh
printf 'Read token: '; read -rs READ_TOKEN; echo
sudo install -m 600 /dev/null /etc/apt/auth.conf.d/apt.conf
printf 'machine %s login YOUR_USERNAME password %s\n' https://repo.example.com/debian/apt "$READ_TOKEN" \
  | sudo tee -a /etc/apt/auth.conf.d/apt.conf > /dev/null
```

## Download raw files

A raw repository keeps any file at any path. The examples use a raw repository named `files`.

```sh
curl -fL -O https://repo.example.com/raw/files/app/app-1.2.0.tar.gz
```

For a private repository, give `curl` your username and a read token on stdin:

```sh
printf 'Read token: '; read -rs READ_TOKEN; echo
printf 'user = "YOUR_USERNAME:%s"\n' "$READ_TOKEN" \
  | curl -fL -K - -O https://repo.example.com/raw/files/app/app-1.2.0.tar.gz
```

## Publish Debian packages and raw files

Set up the project as in [Publish from a project](/publish-from-a-project/#set-up-the-project). In a Debian or raw repository, the CLI asks for the folder of a raw repository, or the distribution and the component of a Debian repository. It writes the answers to `telesphorepo.toml`. Commit the file.

For a Debian repository named `apt`, the file is this:

```toml title="telesphorepo.toml"
server = "https://repo.example.com"
repo = "apt"
dist = "stable"
component = "main"
```

For a raw repository named `files`, `path` is the folder in the repository:

```toml title="telesphorepo.toml"
server = "https://repo.example.com"
repo = "files"
path = "app"
```

Then publish the files with the CLI, on your computer or in CI:

```sh
telesphorepo publish my-package_1.0.0_amd64.deb
telesphorepo publish app-1.2.0.tar.gz
```

The CLI sends a file of 64 MiB or more in parts, and sends a failed part again. A Debian repository builds and signs its indexes about 2 seconds after an upload.

In CI, the CLI publishes with the identity token of the job. See [Publish from CI](/publish-from-ci/). The **Publish to this repository** tab shows the CI files.

You can also upload in the browser: open the repository and click **Upload**.

### Upload with curl and a publish token

To upload with `curl`, you need a publish token:

1. Open **Settings** › **Tokens**, and click **New publish token**.
2. Choose the repository, and click **Continue**.
3. Confirm with your second factor, and click **Create token**.
4. Copy the token. It starts with `trs_` and works for 15 minutes.

Publish tokens are for accounts with a password and **Publish** on the repository. Paste the token at the hidden prompt, so it stays out of the shell history and the process list.

A Debian package goes to a path that names the distribution (`stable`) and the component (`main`):

```sh
printf 'Publish token: '; read -rs TOKEN; echo
printf 'user = "publish:%s"\n' "$TOKEN" | curl -fsS -K - -T my-package_1.0.0_amd64.deb \
  https://repo.example.com/debian/apt/upload/stable/main
```

A raw file goes to its path in the repository:

```sh
printf 'Publish token: '; read -rs TOKEN; echo
printf 'user = "publish:%s"\n' "$TOKEN" | curl -fsS -K - -T app-1.2.0.tar.gz \
  https://repo.example.com/raw/files/app/app-1.2.0.tar.gz
```

A file goes to a Maven repository the same way:

```sh
printf 'Publish token: '; read -rs TOKEN; echo
printf 'user = "publish:%s"\n' "$TOKEN" | curl -fsS -K - -T my-lib-1.0.0.jar \
  https://repo.example.com/maven/releases/com/example/my-lib/1.0.0/my-lib-1.0.0.jar
```

## If something goes wrong

A Debian upload fails for its architecture

A new Debian repository takes the architectures `amd64` and `arm64`, and packages for `all`. Change the list in **Architectures** on the **Format settings** tab of the repository settings. An upload with another architecture fails. The server builds the package lists of an added architecture, and removes those of a removed one.

409 when you upload a Debian package

An upload of the same package and version with other bytes answers `409`. Raise the version.

409 when you replace a raw file

By default, a raw repository refuses other bytes at a path that exists. It answers `409`. To allow a replace, open the repository settings, then the **Format settings** tab. In **Replace files**, choose `allow`, then click **Save**.