From 31f7bfbbcb7763da468387471f087d9bfc326245 Mon Sep 17 00:00:00 2001 From: Sergio <77530549+sergi0g@users.noreply.github.com> Date: Fri, 20 Dec 2024 21:20:50 +0200 Subject: [PATCH] Start updating docs --- docs/components/pages/Home.tsx | 1 - docs/pages/_document.tsx | 4 +- docs/pages/_meta.json | 2 +- .../community-resources/homepage-widget.mdx | 4 +- docs/pages/docs/configuration.mdx | 7 +- .../docs/configuration/authentication.mdx | 12 +++- .../configuration/insecure-registries.mdx | 18 +++-- docs/pages/docs/configuration/theme.mdx | 2 +- docs/pages/docs/usage/cli.mdx | 65 ++++++++----------- docs/theme.config.jsx | 4 ++ 10 files changed, 65 insertions(+), 54 deletions(-) diff --git a/docs/components/pages/Home.tsx b/docs/components/pages/Home.tsx index ea7303f..0cc4ea6 100644 --- a/docs/components/pages/Home.tsx +++ b/docs/components/pages/Home.tsx @@ -57,7 +57,6 @@ export function Home() {
Get started diff --git a/docs/pages/_document.tsx b/docs/pages/_document.tsx index f96fb98..b79695d 100644 --- a/docs/pages/_document.tsx +++ b/docs/pages/_document.tsx @@ -20,8 +20,8 @@ class DocumentProMax extends Document { sizes="180x180" href="/apple-touch-icon.png" /> - - + + :9000/json + url: http://:9000/api/v3/json refreshInterval: 10000 method: GET mappings: diff --git a/docs/pages/docs/configuration.mdx b/docs/pages/docs/configuration.mdx index 83b0078..3bbcd7f 100644 --- a/docs/pages/docs/configuration.mdx +++ b/docs/pages/docs/configuration.mdx @@ -33,7 +33,7 @@ Cup has an option to be configured from a configuration file named `cup.json`. ### Create the configuration file Create a `cup.json` file somewhere on your system. For binary installs, a path like `~/.config/cup.json` is recommended. -If you're running with Docker, you can create a `cup.json` in the directory you're running cup and mount it into the container. _In the next section you will need to use the path where you **mounted** the file_ +If you're running with Docker, you can create a `cup.json` in the directory you're running Cup and mount it into the container. _In the next section you will need to use the path where you **mounted** the file_ ### Configure Cup from the configuration file @@ -66,6 +66,11 @@ Here's a full example: } ``` + +If you want autocompletions and error checking for your editor, there is a JSON schema available. +Use it by adding a `"$schema": "https://raw.githubusercontent.com/sergi0g/cup/main/cup.schema.json"` entry in your `cup.json` file. + + ### Run Cup with the new configuration file To let Cup know that you'd like it to use a custom configuration file, you can use the `-c` flag, followed by the _absolute_ path of the file. diff --git a/docs/pages/docs/configuration/authentication.mdx b/docs/pages/docs/configuration/authentication.mdx index 65eaa25..7e091cf 100644 --- a/docs/pages/docs/configuration/authentication.mdx +++ b/docs/pages/docs/configuration/authentication.mdx @@ -6,9 +6,15 @@ Some registries (or specific images) may require you to be authenticated. For th ```json { - "authentication": { - "": "", - "": "" + "registries": { + "": { + "authentication": "" + // Other options + }, + "" { + "authentication": "" + // Other options + }, // ... } // Other options diff --git a/docs/pages/docs/configuration/insecure-registries.mdx b/docs/pages/docs/configuration/insecure-registries.mdx index 0c717b7..bcc9197 100644 --- a/docs/pages/docs/configuration/insecure-registries.mdx +++ b/docs/pages/docs/configuration/insecure-registries.mdx @@ -2,21 +2,31 @@ import { Callout } from "nextra-theme-docs"; # Insecure registries -For the best security, Cup only connects to registries over SSL (HTTPS) by default. However, for people running a local registry that haven't configured SSL, this may be a problem. +For the best security, Cup only connects to registries over SSL (HTTPS) by default. However, for people running a local registry that doesn't support SSL, this may be a problem. -To solve this problem, `cup.json` has an `"insecure_registries"` option which allows you to specify exceptions +To solve this problem, you can specify exceptions in your `cup.json`. Here's what it looks like: ```json { - "insecure_registries": ["", ""] + "registries": { + "": { + "insecure": true + // Other options + }, + "" { + "insecure": true + // Other options + }, + // ... + } // Other options } ``` When configuring an insecure registry that doesn't run on port 80, don't - forget to specify it (i.e. use `localhost:5000` instead of `localhost` if your + forget to specify the port (i.e. use `localhost:5000` instead of `localhost` if your registry is running on port `5000`) diff --git a/docs/pages/docs/configuration/theme.mdx b/docs/pages/docs/configuration/theme.mdx index d7f16b2..167f742 100644 --- a/docs/pages/docs/configuration/theme.mdx +++ b/docs/pages/docs/configuration/theme.mdx @@ -17,7 +17,7 @@ This was replaced by a more neutral theme which is now the default: Screenshot of neutral theme However, you can get the old theme back by adding the `theme` key to your `cup.json` -Available values are `default` and `blue`. +Available options are `default` and `blue`. Here's an example: diff --git a/docs/pages/docs/usage/cli.mdx b/docs/pages/docs/usage/cli.mdx index bc7cd9e..e60c3ae 100644 --- a/docs/pages/docs/usage/cli.mdx +++ b/docs/pages/docs/usage/cli.mdx @@ -11,66 +11,53 @@ Cup's CLI provides the `cup check` command. ```ansi $ cup check -nginx:alpine Update available -redis:7 Update available + +mysql:8.0 Major update +node:20 Major update +postgres:16-alpine Major update +rust:1.80.1-alpine Minor update +redis:7.4.0 Patch update +nginx:alpine Update available redis:alpine Update available -... -centos:7 Up to date -mcr.microsoft.com/devcontainers/go:0-1.19-bullseye Up to date -rockylinux:9-minimal Up to date -rabbitmq:3.11.9-management Up to date -... -some/deleted:image Unknown -[38:5:86mINFO ✨ Checked 58 images in 3772ms +ubuntu:latest Update available +node:iron Up to date +2fauth/2fauth:latest Up to date +c1982/sdns:latest Up to date +registry.acme.com/acme-server:latest Unknown +INFO ✨ Checked 58 images in 3772ms ``` ### Check for updates to specific images ```ansi -$ cup check node:latest -node:latest Update available -[38:5:86mINFO ✨ Checked 1 images in 1310ms +$ cup check node:latest +node:latest Update available +INFO ✨ Checked 1 images in 1310ms ``` ```ansi -$ cup check node:latest -nextcloud:30 Update available -postgres:14 Update available -mysql:8.0 Up to date -[38:5:86mINFO ✨ Checked 3 images in 1769ms +$ cup check nextcloud:30 postgres:14 mysql:8.0 +nextcloud:30 Update available +postgres:14 Update available +mysql:8.0 Up to date +INFO ✨ Checked 3 images in 1769ms ``` ## Enable icons You can also enable icons if you have a [Nerd Font](https://nerdfonts.com) installed. - +GIF of Cup's CLI ## JSON output When integrating Cup with other services (e.g. webhooks or a dashboard), you may find Cup's JSON output functionality useful. -It provides some useful metrics (see [server](/docs/usage/server) for more information), along with a list of images and whether they have an update or not. +It provides some useful metrics (see [server](/docs/usage/server) for more information), along with a list of images and whether they have an update or not. Note that at the moment it does not match the detailed API the server provides. ``` $ cup check -r -{"metrics":{"update_available":4,"monitored_images":25,"unknown":1,"up_to_date":20},"images":{"ghcr.io/immich-app/immich-server:v1.106.4":false,"portainer/portainer-ce:2.20.3-alpine":false,"ghcr.io/runtipi/runtipi:v3.4.1":false,...}} -``` - -Here is how it would look in Typescript: - -```ts -interface CupData { - metrics: { - monitored_images: number; - up_to_date: number; - update_available: number; - unknown: number; - }; - images: { - [image: string]: boolean | null; - }; -} +{"metrics":{"monitored_images":26,"up_to_date":2,"updates_available":23,"major_updates":8,"minor_updates":6,"patch_updates":2,"other_updates":7,"unknown":1},"images":{"ghcr.io/immich-app/immich-server:v1.106.4":false,"portainer/portainer-ce:2.20.3-alpine":false,"ghcr.io/runtipi/runtipi:v3.4.1":false,...}} ``` ## Usage with Docker @@ -79,12 +66,12 @@ If you're using the Docker image, just replace all occurences of `cup` in the ex For example, this: -```bash /check node:latest/ +```bash $ cup check node:latest ``` becomes: -```bash /check node:latest/ +```bash $ docker run -tv /var/run/docker.sock:/var/run/docker.sock ghcr.io/sergi0g/cup check node:latest ``` diff --git a/docs/theme.config.jsx b/docs/theme.config.jsx index 8cab878..911ea1e 100644 --- a/docs/theme.config.jsx +++ b/docs/theme.config.jsx @@ -10,6 +10,10 @@ export default { return { titleTemplate: "Cup – %s", }; + } else { + return { + titleTemplate: "%s" + } } }, head: () => {