Reference
Server commands
Section titled “Server commands”| Command | What it does |
|---|---|
telesphorepo-server serve |
Runs the server. telesphorepo-server with no command does the same. |
telesphorepo-server dev |
Runs a local server with demo repositories and demo data. Add --empty for empty repositories. |
telesphorepo-server user add NAME [--admin] |
Creates a user. It asks for the password. |
telesphorepo-server user passwd NAME |
Sets a new password and signs the user out everywhere. |
telesphorepo-server user reset-2fa NAME |
Removes every second factor of the user. |
telesphorepo-server version |
Prints the version. |
telesphorepo-server help [command] |
Shows the help of a command. |
In the container, put docker exec -it telesphorepo /telesphorepo-server before the command. The user commands change the database in TR_DATA_DIR.
CLI commands
Section titled “CLI commands”The server serves the Telesphorepo CLI of its own version. Install it with curl -fsSL https://repo.example.com/install.sh | sh, or on Windows with irm https://repo.example.com/install.ps1 | iex. See Install the CLI.
| Command | What it does |
|---|---|
telesphorepo setup LINK |
Sets up the project of this folder from the setup line of the Publish to this repository tab. It approves the computer and writes telesphorepo.toml. For a Docker repository, it adds the credential helper to the Docker config. |
telesphorepo publish [FILE...] |
Publishes the project of this folder: Gradle, Maven, npm, Python, Cargo, .NET or a Helm chart. For a raw or Debian repository, it uploads each FILE. For Python and .NET, FILE names wheels, sdists or .nupkg files to upload with no build. |
telesphorepo login SERVER |
Approves this computer for a server, with no project. |
telesphorepo logout [SERVER] |
Revokes the approval of this computer, and removes its files and its Docker helper entries. |
telesphorepo status |
Shows the approvals of this computer and the project of this folder. It shows no secret. |
telesphorepo update [SERVER] |
Installs the CLI of the server. A newer CLI stays, because it works with an older server. |
telesphorepo version |
Prints the version. |
telesphorepo help [command] |
Shows the help of a command, with examples. |
The CLI keeps the key of each approved computer in ~/.telesphorepo/<server>/device.json. Only you can read the file.
telesphorepo.toml
Section titled “telesphorepo.toml”| Key | What it sets |
|---|---|
server |
The address of the server |
repo |
The repository |
kind |
maven or gradle, when the folder holds both |
path |
The folder in a raw repository |
dist, component |
The distribution and the component of a Debian repository |
CI variables
Section titled “CI variables”| Variable | What it sets |
|---|---|
OIDC_TOKEN |
The identity token of a Jenkins job. Its audience must be the address of the server. GitHub Actions needs no variable: the job needs id-token: write. |
TELESPHOREPO_SERVER |
The server of the Docker credential helper in CI |
Environment variables
Section titled “Environment variables”No variable is required.
| Variable | Default | What it sets |
|---|---|---|
TR_DATA_DIR |
./data, /data in the image |
The folder for the database, the files and the master key |
TR_LISTEN |
:8080 |
The listen address |
TR_MASTER_KEY |
a file in the data folder | The key that encrypts secret settings: 32 bytes, base64 |
TR_BOOTSTRAP_ADMIN_USER, TR_BOOTSTRAP_ADMIN_PASSWORD |
admin and a random password |
The first admin. The server reads them only while it has no users |
A change to these variables needs a restart.
Settings
Section titled “Settings”Change settings in the web UI, on the pages General, Storage, Sign-in options and Network and proxy under Settings. A change applies at once.
You can also force any setting from the environment. The name is TR_ plus the key in capitals, with _ for each .. For example, s3.bucket becomes TR_S3_BUCKET. The web UI then shows the setting as read only.
All settings
| Key | Default | What it sets |
|---|---|---|
base_url |
none | The address that clients use (Public base URL on the General page) |
log.level |
info |
The log level |
max_upload_size |
2GiB |
The largest upload (Max upload size) |
max_json_size |
1MiB |
The largest API request body |
nexus.sync_interval |
15m |
The time between two Nexus syncs, at least 1m |
storage |
fs |
fs for the local disk, s3 for a bucket (R2 and SeaweedFS are S3 buckets) |
fs.root |
blobs/ in the data folder |
The folder for files on the local disk |
s3.endpoint, s3.bucket, s3.access_key_id, s3.secret_access_key |
none | The bucket and its keys. An empty s3.endpoint means AWS |
s3.region |
none | The region of the bucket. AWS needs it. With an endpoint and no region, the server uses auto |
s3.prefix |
none | A prefix for every object name |
s3.path_style |
false |
Path-style addresses, for SeaweedFS and MinIO |
s3.redirect |
true |
Send downloads straight from the bucket |
presign_ttl |
5m |
How long a bucket download link works |
cookie.secure |
true |
Send the session cookie over HTTPS only |
session_ttl |
168h |
How long a web session lasts |
trusted_proxies |
none | The reverse proxies that the server trusts |
audit.retention |
8760h |
How long the audit log keeps events |
publish.session_ttl |
15m |
How long a publish token works, at most 1h |
publish.device_ttl |
2160h |
How long an approved computer can publish |
oidc.issuer, oidc.client_id, oidc.client_secret |
none | The single sign-on provider |
oidc.redirect_url |
base_url + /api/auth/oidc/callback |
The redirect address at the provider |
oidc.scopes |
openid profile email |
The scopes to ask for |
oidc.permission_claim |
none | The claim of the sign-in token whose values give server permissions |
oidc.permission_map |
{} |
For each value of the claim, the server permissions it gives, such as {"repo-admins": ["repositories.all"]} |
oidc.session_ttl |
12h |
How long a single sign-on session lasts |
signin.password_login |
all |
all: every local account can sign in with a password. publishers: a person who manages signs in with single sign-on only |
index.debounce |
2s |
How long the server waits before it builds the indexes of a repository again |
index.max_delay |
30s |
The longest wait before the indexes build |
blobs.gc_grace |
1h |
How long a file that no repository uses stays on the storage |
upload.session_ttl |
24h |
How long a resumable upload can wait for its next part |
docker.direct_uploads |
false |
Send the layer bytes of a push to docker.upload_url (Expose the origin IP for Docker uploads). Behind Cloudflare, it lets a layer be larger than 100 MB. It makes the IP address of the server public |
docker.upload_url |
none | The DNS-only name or address of the server that takes the layer bytes (Docker upload address), such as https://upload.example.com. Only a scheme and a host. Needed when docker.direct_uploads is on |
docker.link_grace |
24h |
How long a Docker layer that no image uses stays before the server removes it, at least 1s |
tls.cert_file, tls.key_file |
none | A certificate and a key (PEM) for HTTPS in the server. Set both or neither. They apply at the next start |
Repository addresses
Section titled “Repository addresses”The examples use the server https://repo.example.com and a repository named REPO.
| Format | Kinds | Address for clients |
|---|---|---|
| Maven / Gradle | hosted, proxy, group | https://repo.example.com/maven/REPO |
| npm | hosted, proxy, group | https://repo.example.com/npm/REPO/ |
| Python (PyPI) | hosted, proxy, group | https://repo.example.com/pypi/REPO/simple/ to install, https://repo.example.com/pypi/REPO/ to upload |
| Cargo (Rust) | hosted, proxy, group | sparse+https://repo.example.com/cargo/REPO/index/ |
| NuGet | hosted, proxy, group | https://repo.example.com/nuget/REPO/index.json |
| Docker | hosted, proxy, group | repo.example.com/REPO/IMAGE:TAG, at the root of the host |
| Debian (apt) | hosted, proxy | https://repo.example.com/debian/REPO |
| Raw files | hosted | https://repo.example.com/raw/REPO |
A proxy keeps a copy of each file that people download from its remote. A group serves its members in order, and takes no uploads. In a group of npm, Python, Cargo or NuGet repositories, the first member that has a package name owns it: the group serves every version of that name from that member only, so a public package cannot shadow a private one. A Maven group merges maven-metadata.xml over its members, so the versions of all members show. A Docker group serves each file from the first member that has it, and lists the tags of all members.
HTTP API
Section titled “HTTP API”The web UI uses a JSON API under /api/. The full list of routes is in SPEC.md in the source repository.
GET /healthz answers ok when the server runs. Use it for health checks.
Licenses
Section titled “Licenses”The server is AGPL-3.0. The Telesphorepo CLI and its Docker credential helper are MIT.
Your artifacts stay yours. Files that you store on the server do not fall under the AGPL. If you change the server and let other people use it over a network, offer them the source of your changed version.