diff --git a/flake.nix b/flake.nix index bb2365e..452ef1d 100644 --- a/flake.nix +++ b/flake.nix @@ -25,7 +25,6 @@ default = pkgs.mkShell { buildInputs = with pkgs; [ nodejs_24 - openssh ]; shellHook = '' diff --git a/src/components/elements/MinorHeader.vue b/src/components/elements/MinorHeader.vue new file mode 100644 index 0000000..3b4f576 --- /dev/null +++ b/src/components/elements/MinorHeader.vue @@ -0,0 +1,39 @@ + + + + + diff --git a/src/components/elements/TipBlock.vue b/src/components/elements/TipBlock.vue new file mode 100644 index 0000000..ce488b6 --- /dev/null +++ b/src/components/elements/TipBlock.vue @@ -0,0 +1,45 @@ + + + + + diff --git a/src/views/DocumentationV6View.vue b/src/views/DocumentationV6View.vue index 7def74e..b8d41ea 100644 --- a/src/views/DocumentationV6View.vue +++ b/src/views/DocumentationV6View.vue @@ -4,7 +4,9 @@ import TextBlock from "../components/elements/TextBlock.vue"; import WarnBlock from "../components/elements/WarnBlock.vue"; import TableBlock from "../components/elements/TableBlock.vue"; import SubHeader from "../components/elements/SubHeader.vue"; +import MinorHeader from "../components/elements/MinorHeader.vue"; import MainHeader from "../components/elements/MainHeader.vue"; +import TipBlock from "../components/elements/TipBlock.vue"; import ConfigCard from "../components/elements/ConfigCard.vue"; import ConfigGrid from "../components/elements/ConfigGrid.vue"; @@ -64,13 +66,13 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue";
  • Installation
  • Uninstall
    • @@ -121,14 +123,55 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue";
    Installation - There are several methods to install Kellnr. Check all options and chose the right one - for you. + Kellnr can be installed in several ways. Use the table below to jump to the method that + fits your use case, or read through the options one by one. - Docker Container + Which Method? + + Not sure where to start? Pick the row that matches what you want to do. + + + + + I want to… + Recommended method + + + + + Quickly try out Kellnr + Docker + + + Run Kellnr on Kubernetes + Kubernetes (Helm) + + + Run a standalone binary on Linux, Windows, or macOS + Pre-built Binaries + + + Install on a Linux server as a systemd service + Install Script + + + Install through my distribution (Arch, NixOS, …) + Package Managers + + + Build Kellnr from source + Build from Source + + + + + Docker + + Running Kellnr as a Docker container is the easiest way to get started — no further + installation steps are required. + - The easiest way to run Kellnr is a Docker container, as no further installation steps - are required. You can find the latest version tag on the Kellnr images page. There is a minimal image, which does not support building rustdocs with @@ -159,56 +202,152 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; the container with a mounted volume for persistence, all variables are ignored. - Package Managers + Kubernetes (Helm) - Kellnr can be found in the Arch User Repo (aur): Kellnr - AUR - If you use the yay package manager you can install Kellnr with - the following command. + The recommended way to install Kellnr on Kubernetes is with a Helm Chart. You can find the + documentation for installing Kellnr with a Helm Chart here: Kellnr + Helm Chart + + + Pre-built Binaries + + Pre-built binaries for Linux, Windows, and macOS are published as release assets on + GitHub. The links below always point to the latest release. Download the archive for + your platform, extract it, and run Kellnr directly. You can also browse all versions on + the GitHub Releases page. + + + + + Platform + Architecture + Download + + + + + Linux (glibc) + x86_64 + kellnr-x86_64-unknown-linux-gnu.zip + + + Linux (glibc) + ARM64 + kellnr-aarch64-unknown-linux-gnu.zip + + + Linux (musl, static) + x86_64 + kellnr-x86_64-unknown-linux-musl.zip + + + Linux (musl, static) + ARM64 + kellnr-aarch64-unknown-linux-musl.zip + + + Windows + x86_64 + kellnr-x86_64-windows.zip + + + Windows + ARM64 + kellnr-aarch64-windows.zip + + + macOS (Apple Silicon) + ARM64 + kellnr-aarch64-apple-darwin.zip + + + + + Linux + + Required dependencies: curl and unzip. Set $ARCH + to the target that matches your system: + - # Install Kellnr with yay - yay -S kellnr + # Download the latest release (set $ARCH to your target, see above) + curl -L -o kellnr-latest.zip \ + "https://github.com/kellnr/kellnr/releases/latest/download/kellnr-$ARCH.zip" + + # Unzip + unzip -o kellnr-latest.zip -d ./kellnr + cd ./kellnr + + # (Optional) Create a configuration file + ./kellnr config init -o kellnr.toml + # Edit kellnr.toml to set admin_pwd, origin hostname, etc. + + # Open the configured port (default 8000), then start Kellnr + ./kellnr start -d /path/to/data/dir + + # Or start with a configuration file + ./kellnr -c kellnr.toml start + Windows - Nix Flake
    - Kellnr provides a Nix flake that can be used to run Kellnr directly or install it into your - system profile. The flake supports x86_64-linux, aarch64-linux, - x86_64-darwin, and aarch64-darwin. + Download the archive for your architecture, extract it, and run Kellnr directly. +     - - # Run Kellnr directly without installing - nix run github:kellnr/kellnr -- start -d /path/to/data/dir + + # Download and extract (PowerShell) + Invoke-WebRequest -Uri "https://github.com/kellnr/kellnr/releases/latest/download/kellnr-x86_64-windows.zip" -OutFile kellnr.zip + Expand-Archive kellnr.zip -DestinationPath kellnr + cd kellnr - # Install Kellnr into your profile - nix profile install github:kellnr/kellnr + # (Optional) Create a configuration file + .\kellnr.exe config init -o kellnr.toml - # Start Kellnr after installing - kellnr start -d /path/to/data/dir + # Start Kellnr + .\kellnr.exe start -d C:\path\to\data\dir + + The Windows binaries are not tested and are provided on a best-effort basis. If you encounter + any issues, please report them on GitHub. + + + macOS - To use Kellnr as an input in your own flake (e.g. for a NixOS module or development shell): + Pre-built macOS binaries for Apple Silicon are published as release assets on GitHub. The + binary is signed with an Apple Developer ID and notarized by Apple, so it runs without any + Gatekeeper warnings after downloading. + - - { - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; - kellnr.url = "github:kellnr/kellnr"; - }; + + # Download and extract + curl -L -o kellnr-latest.zip \ + "https://github.com/kellnr/kellnr/releases/latest/download/kellnr-aarch64-apple-darwin.zip" + unzip -o kellnr-latest.zip -d ./kellnr + cd ./kellnr - outputs = { nixpkgs, kellnr, ... }: { - # Use kellnr.packages.${system}.default - }; - } + # (Optional) Create a configuration file + ./kellnr config init -o kellnr.toml + + # Start Kellnr with the data directory + ./kellnr start -d /path/to/data/dir - Script + Install Script The installation script is tested on current Debian Server versions. Any other modern Linux distribution may work, but we cannot guarantee that. If the script does not work for your distribution, try the -m flag. This forces the installer script to use a static binary compiled with musl, - which works independent of any distribution. If that does not work, have a look at "Manual Installation". + which works independent of any distribution. If that does not work, have a look at the + Pre-built Binaries section. The script will automatically install the right version for your architecture. Currently supported are x64 and aarch64 (arm64).

    @@ -294,117 +433,105 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; - Cargo Install + Package Managers - If you have Rust and Cargo installed on your system, you can install Kellnr with Cargo as - well. This will build Kellnr from source on your system. + Kellnr can be found in the Arch User Repo (aur): Kellnr - AUR + If you use the yay package manager you can install Kellnr with + the following command. - # Install Kellnr with Cargo - cargo install kellnr - # If you run into issues with OpenSSL, try the following command: - cargo install kellnr --features vendored-openssl - # Start kellnr (if not in PATH, the binary is located in $HOME/.cargo/bin/) - kellnr start -d /path/to/data/dir + # Install Kellnr with yay + yay -S kellnr - Manual Installation - Manually installing Kellnr is possible as well. If the Docker or script approach does not - work for you, this is the best alternative.
    -
    - Required dependencies: -
      -
    • zip (unzip)
      • -
    • curl
      • -
    + Nix Flake
    + Kellnr provides a Nix flake that can be used to run Kellnr directly or install it into your + system profile. The flake supports x86_64-linux, aarch64-linux, + x86_64-darwin, and aarch64-darwin.     - # Download latest Kellnr version - # $ARCH can be: - # - x86_64-unknown-linux-gnu - # - aarch64-unknown-linux-gnu - # - x86_64-unknown-linux-musl - # - aarch64-unknown-linux-musl - curl --output kellnr-latest.zip - "https://github.com/kellnr/kellnr/releases/latest/download/kellnr-$ARCH.zip" - - # Unzip - unzip -o kellnr-latest.zip -d ./kellnr - cd ./kellnr - - # (Optional) Create a configuration file - ./kellnr config init -o kellnr.toml - # Edit kellnr.toml to set admin_pwd, origin hostname, etc. - - # Open the ports (default 8000) + # Run Kellnr directly without installing + nix run github:kellnr/kellnr -- start -d /path/to/data/dir - # Start Kellnr with the data directory - ./kellnr start -d /path/to/data/dir + # Install Kellnr into your profile + nix profile install github:kellnr/kellnr - # Or start with a configuration file - ./kellnr -c kellnr.toml start + # Start Kellnr after installing + kellnr start -d /path/to/data/dir - - Helm Chart - The recommended way to install Kellnr on Kubernetes is with a Helm Chart. You can find the - documentation for installing Kellnr with a Helm Chart here: Kellnr - Helm Chart - - - Windows - - Pre-built Windows binaries are published as release assets on GitHub for every release. - Download the archive for your architecture, extract it, and run Kellnr directly. - - You can find all releases on the GitHub Releases page. + To use Kellnr as an input in your own flake (e.g. for a NixOS module or development shell): - - # Download and extract (PowerShell) - Invoke-WebRequest -Uri "https://github.com/kellnr/kellnr/releases/latest/download/kellnr-x86_64-windows.zip" -OutFile kellnr.zip - Expand-Archive kellnr.zip -DestinationPath kellnr - cd kellnr - - # (Optional) Create a configuration file - .\kellnr.exe config init -o kellnr.toml + + { + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + kellnr.url = "github:kellnr/kellnr"; + }; - # Start Kellnr - .\kellnr.exe start -d C:\path\to\data\dir + outputs = { nixpkgs, kellnr, ... }: { + # Use kellnr.packages.${system}.default + }; + } - - The Windows binaries are not tested and are provided on a best-effort basis. If you encounter - any issues, please report them on GitHub. - - - Uninstall + Build from Source - To uninstall Kellnr and delete all data (crates, users, ...), if you installed it manully, - execute the uninstall script besides the Kellnr installation directory. + If you have Rust and Cargo installed on your system, you can install Kellnr with Cargo. + This builds Kellnr from source on your machine. - - # Change to the directory containing the Kellnr installation - cd ~ - # Run the uninstaller - curl -s https://raw.githubusercontent.com/kellnr/installer/main/uninstall.sh | sudo bash + # Install Kellnr with Cargo + cargo install kellnr + # If you run into issues with OpenSSL, try the following command: + cargo install kellnr --features vendored-openssl + # Start kellnr (if not in PATH, the binary is located in $HOME/.cargo/bin/) + kellnr start -d /path/to/data/dir + Uninstall - If you installed Kellnr with the Helm Chart run the command below. Beware that all data - (crates, users, ...) will be deleted if you created the PersistentVolume with the - Helm chart. + How you remove Kellnr depends on how you installed it. In every case, Kellnr keeps all its + data (crates, users, settings) in the data directory you passed with -d (or + the mounted Docker volume). Deleting that directory removes all data permanently, so back + it up first if you might need it again. - - - # Uninstall Kellnr Helm Chart - helm uninstall kellnr - + + + + Installed via + How to remove + + + + + Docker + docker rm -f kellnr, then delete the mounted data directory. + + + Pre-built binary (Linux/Windows/macOS) + Delete the extracted Kellnr directory and the data directory. + + + Install Script (systemd) + Run the uninstaller from besides the installation directory:
    curl -s https://raw.githubusercontent.com/kellnr/installer/main/uninstall.sh | sudo bash + + + Package Managers + yay -Rns kellnr (AUR) or nix profile remove kellnr (Nix). + + + Cargo + cargo uninstall kellnr, then delete the data directory. + + + Kubernetes (Helm) + helm uninstall kellnr. Deletes all data if the PersistentVolume was created by the chart. + + +     Configuration @@ -425,7 +552,7 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; Kellnr can use a TOML configuration file. You can generate a default configuration file using kellnr config init or specify a custom config file path with the -c - flag (e.g., kellnr -c /etc/kellnr.toml run). Values from the config file can be + flag (e.g., kellnr -c /etc/kellnr.toml start). Values from the config file can be overwritten by environment variables or CLI arguments. See below for possible values. @@ -446,7 +573,22 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; overwritten after the first start of Kellnr, except through the UI of Kellnr. -
    Setup
    + + + Setup @@ -455,7 +597,7 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; description="Authentication token for the admin user. Used on first start only. If not set, no token is created and the user must create one via the web UI." /> -
    Registry
    + Registry -
    Local Server
    + Local Server @@ -521,7 +663,7 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; description="Port where Kellnr listens." /> -
    Origin (External Access)
    + Origin (External Access) -
    Logging
    + Logging @@ -546,7 +688,7 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; description="Format of the log output. Either 'compact', 'pretty' or 'json'." /> -
    Crates.io Proxy
    + Crates.io Proxy -
    Documentation
    + Documentation -
    PostgreSQL
    + PostgreSQL @@ -601,7 +743,7 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; description="Password of the PostgreSQL database." /> -
    S3 Storage
    + S3 Storage @@ -630,7 +772,7 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; description="S3 request timeout in seconds." /> -
    OAuth2/OIDC
    + OAuth2/OIDC @@ -663,7 +805,7 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; default-value="Login with SSO" description="Text displayed on the OAuth2 login button in the web UI." /> -
    Toolchain Server
    + Toolchain Server CLI Arguments - All configuration values can be set via CLI arguments when using the run command. + All configuration values can be set via CLI arguments when using the start command. CLI arguments take precedence over environment variables and configuration file values. -
    Global Options
    + Global Options @@ -1125,7 +1267,7 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; -
    Server Options (start command)
    + Server Options (start command) @@ -1178,7 +1320,7 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; -
    Feature Flags (start command)
    + Feature Flags (start command) @@ -1267,15 +1409,15 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue";
      -
    • /.cargo/config
      • -
    • /projects/.cargo/config
      • -
    • /projects/proj1/.cargo/config
      • -
    • /projects/proj1/subproj/.cargo/config
      • +
    • /.cargo/config.toml
      • +
    • /projects/.cargo/config.toml
      • +
    • /projects/proj1/.cargo/config.toml
      • +
    • /projects/proj1/subproj/.cargo/config.toml
    Cargo will use the configured registry for the corresponding project.

    - The config file is the same format at described in the Global Configuration above. + The config file is the same format as described in the Global Configuration above.     Pull & Publish to Kellnr @@ -1287,8 +1429,8 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; # Example Cargo.toml which uses a dependency from Kellnr # The registry name has to be the one defined in .cargo/config.toml [package] - authors = ["myauthor "] - edition = "2018" + authors = ["myauthor"] + edition = "2021" name = "my_crate" version = "0.1.0" @@ -1299,8 +1441,8 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; # Example Cargo.toml to publish to Kellnr # The publish name has to be the one defined in .cargo/config.toml [package] - authors = ["myauthor "] - edition = "2018" + authors = ["myauthor"] + edition = "2021" name = "my_crate" version = "0.1.0" publish = ["kellnr"] @@ -1325,18 +1467,18 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; instead of crates.io as the source for all crates. The official cargo documentation for source replacements can be found here: Source - Replacement in Cargo. All configuration of the proxy takes place in the same .cargo/config + Replacement in Cargo. All configuration of the proxy takes place in the same .cargo/config.toml file as described above. Pull only specific Crates from Kellnr Proxy If you want to pull only specific crates from the Kellnr proxy, you can do that by specifying - the Kellnr crates.io index either per project in the .cargo/config file or globally in - the ~./.cargo/config file. + the Kellnr crates.io index either per project in the .cargo/config.toml file or globally in + the ~/.cargo/config.toml file. - # .cargo/config + # .cargo/config.toml # Set the Kellnr crates.io proxy. Important is the path "/cratesio". [registries.kellnr-cratesio] @@ -1359,11 +1501,11 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; Replace Crates.io with Kellnr Proxy Cache Instead of specifying for each crate that Kellnr should be used as the source, cargo can replace - a source with another. To replace crates.io with the Kellnr proxy edit the .cargo/config + a source with another. To replace crates.io with the Kellnr proxy edit the .cargo/config.toml in your project or home folder. - # .cargo/config + # .cargo/config.toml [source.crates-io] replace-with = "kellnr-cratesio" [source.kellnr-cratesio] @@ -1470,7 +1612,9 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue"; or CLI argument (-d / --registry-data-dir). To backup Kellnr, simply backup the data folder. The data folder contains all data needed to restore Kellnr. It is recommended to backup the data folder regularly, as it contains all uploaded crates and the SQLite database. If you use - PostgreSQL instead, do not forget to backup the database separately. + PostgreSQL instead, do not forget to backup the database separately. Likewise, if you enable + S3 storage, your uploaded crates are stored in the configured + S3 buckets rather than the data folder — back those up separately as well.
    @@ -1481,6 +1625,45 @@ import ConfigGrid from "../components/elements/ConfigGrid.vue";