Debian, raw and curl

This page sets up apt and curl to install and download from Telesphorepo. To publish packages and files, see Publish from a project, under Publish your packages; what is different for Debian and raw files is under 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:

   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:

   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:

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.

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.

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:

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. 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:

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:

telesphorepo.toml

server = "https://repo.example.com"
repo = "files"
path = "app"

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

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. 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):

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:

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:

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.