Add documentation

docs/pages/docs/_meta.json

@@ -0,0 +1,8 @@
+{
+    "index": {
+        "title": "Introduction"
+    },
+    "nightly": {
+        "title": "Using the latest version"
+    }
+}

docs/pages/docs/configuration.mdx

@@ -0,0 +1,98 @@
+import Image from "next/image";
+import { Steps, Callout } from "nextra-theme-docs";
+import blue from "../../assets/blue_theme.png"
+import gray from "../../assets/gray_theme.png"
+
+# Configuration
+
+## Custom docker socket
+
+Sometimes, there may be a need to specify a custom docker socket. Cup provides the `-s` option for this.
+
+For example, if using Podman, you might do
+
+```
+$ cup -s /run/user/1000/podman/podman.sock check
+```
+
+## Configuration file
+
+Cup has an option to be configured from a configuration file named `cup.json`.
+
+<Steps>
+### 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_
+
+### Configure Cup from the configuration file
+Follow the guides below (Theme and Authentication) to make your `cup.json`
+
+Here's a full example:
+```json
+{
+    authentication: {
+        "ghcr.io": "<YOUR_TOKEN_HERE>",
+        "registry-1.docker.io": "<YOUR_TOKEN_HERE>"
+    },
+    theme: "blue"
+}
+```
+
+### 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.
+
+```bash
+$ cup -c /home/sergio/.config/cup.json check
+```
+
+```bash
+$ docker run -tv /var/run/docker.sock:/var/run/docker.sock -v /home/sergio/.config/cup.json:/config/cup.json ghcr.io/sergi0g/cup -c /config/cup.json serve
+```
+</Steps>
+
+## Theme (server only)
+
+Cup initially had a blue theme which looked like this:
+
+<Image alt="Screenshot of blue theme" src={blue} />
+
+This was replaced by a more neutral theme which is now the default:
+
+<Image alt="Screenshot of neutral theme" src={gray} />
+
+However, you can get the old theme back by adding the `theme` key to your `cup.json`
+Available values are `default` and `blue`.
+
+Here's an example:
+
+```json
+{
+    "theme": "blue",
+    // Other options
+}
+```
+
+## Authentication
+
+<Callout emoji="⛔">
+The features described in this section have not been implemented yet.
+</Callout>
+
+Some registries (or specific images) may require you to be authenticated. For those, you can modify `cup.json` like this:
+
+```json
+{
+    "authentication": {
+        "<YOUR_REGISTRY_DOMAIN_1>": "<YOUR_TOKEN_1>",
+        "<YOUR_REGISTRY_DOMAIN_2>": "<YOUR_TOKEN_2>"
+        // ...
+    },
+    // Other options
+}
+```
+
+You can use any registry, like `ghcr.io`, `quay.io`, `gcr.io`, etc.
+
+<Callout emoji="⚠️">
+For Docker Hub, use `registry-1.docker.io`
+</Callout>

docs/pages/docs/index.mdx

@@ -0,0 +1,26 @@
+import Image from "next/image";
+import cup from "../../assets/cup.gif";
+import { Cards, Card } from "nextra-theme-docs";
+import { IconBrandDocker, IconPackage } from "@tabler/icons-react";
+
+# Introduction
+
+<Image src={cup} unoptimized />
+
+Cup is a lightweight alternative to [What's up Docker?](https://github.com/fmartinou/whats-up-docker) written in Rust.
+
+# Features ✨
+
+- 🚀 Extremely fast. Cup takes full advantage of your CPU and is hightly optimized, resulting in lightning fast speed. On my test machine, it took ~6 seconds for 70 images.
+- Supports most registries, including Docker Hub, ghcr.io, Quay, lscr.io and even Gitea (or derivatives)
+- Doesn't exhaust any rate limits. This is the original reason I created Cup. It was inspired by What's up docker? which would always use it up.
+- Beautiful CLI and web interface for checking on your containers any time.
+- The binary is tiny! At the time of writing it's just 4.7 MB. No more pulling 100+ MB docker images for a such a simple program.
+- JSON output for both the CLI and web interface so you can connect Cup to integrations. It's easy to parse and makes webhooks and pretty dashboards simple to set up!
+
+# Installation
+
+<Cards>
+    <Card icon={<IconBrandDocker />} title="With Docker" href="/docs/installation/docker" />
+    <Card icon={<IconPackage />} title="As a binary" href="/docs/installation/binary" />
+</Cards>

docs/pages/docs/installation/_meta.json

@@ -0,0 +1,8 @@
+{
+    "docker": {
+        "title": "With Docker"
+    },
+    "binary": {
+        "title": "As a binary"
+    }
+}

docs/pages/docs/installation/binary.mdx

@@ -0,0 +1,25 @@
+import { Callout, Card, Steps } from "nextra-theme-docs";
+import { IconFileDescription } from "@tabler/icons-react";
+
+# As a binary
+## Introduction
+
+This guide will help you install Cup from a binary.
+
+## Installation
+
+<Steps>
+### Download binary
+Go to https://github.com/sergi0g/cup/releases/latest.
+
+Depending on your system's architecture, choose the binary for your system. For example, for an `x86_64` machine, you should download `cup-x86_64-unknown-linux-musl`
+<Callout>
+You can use the command `uname -i` to find this
+</Callout>
+### Add binary to path
+Move the binary you downloaded to a directory in your path. You can usually get a list those directories by running `echo $PATH`. On most Linux systems, moving it to `~/.local/bin` is usually enough.
+</Steps>
+
+That's it! Cup is ready to be used. Head over to the Usage page to get started.
+<br />
+<Card icon={<IconFileDescription />} title="Usage" href="/docs/usage" />

docs/pages/docs/installation/docker.mdx

@@ -0,0 +1,21 @@
+import { Callout, Card } from "nextra-theme-docs";
+import { IconFileDescription } from "@tabler/icons-react";
+
+# With Docker
+## Introduction
+
+This guide will help you install Cup as a Docker container. It is the easiest installation method and also makes updating Cup very easy.
+
+## Installation
+
+To get started, open up a terminal and run the following command.
+```bash
+$ docker pull ghcr.io/sergi0g/cup
+```
+<Callout emoji="⚠️">
+If you aren't in the `docker` group, please ensure you run all commands as a user who does. In most cases, you'll just need to prefix the `docker` commands with `sudo`
+</Callout>
+
+That's it! Cup is ready to be used. Head over to the Usage page to get started.
+<br />
+<Card icon={<IconFileDescription />} title="Usage" href="/docs/usage" />

docs/pages/docs/nightly.mdx

@@ -0,0 +1,21 @@
+import { Callout } from "nextra-theme-docs"
+
+# Using the latest version
+
+The installation instructions you previously followed describe how to install Cup's stable version.
+
+However, it is only updated when a new release is created, so if you want the latest features, you'll need to install Cup's nightly version.
+
+Cup's nightly version always contains the latest changes in the main branch.
+
+<Callout emoji="⚠️">
+There is no guarantee that the nightly version will always work. There may be breaking changes or a bad commit and it may not work properly. Install nightly only if you know what you are doing. These instructions will assume you have the technical know-how to follow them. If you do not, please use the stable release
+</Callout>
+
+## With Docker
+
+Instead of `ghcr.io/sergi0g/cup`, use `ghcr.io/sergi0g/cup:nightly`
+
+## As a binary
+
+Go to a [nightly workflow run](https://github.com/sergi0g/cup/actions/workflows/nightly.yml) and download the artifact for your system.

docs/pages/docs/usage.mdx

@@ -0,0 +1,11 @@
+import { IconServer, IconTerminal } from "@tabler/icons-react";
+import { Cards, Card } from "nextra-theme-docs";
+
+# Usage
+
+You can use Cup in 2 different ways. As a CLI or as a server. You can learn more about each mode in its corresponding page
+
+<Cards>
+    <Card icon={<IconTerminal />} title="CLI" href="/docs/usage/cli" />
+    <Card icon={<IconServer />} title="Server" href="/docs/usage/server" />
+</Cards>

docs/pages/docs/usage/cli.mdx

@@ -0,0 +1,73 @@
+import Image from "next/image";
+import cup from "../../../assets/cup.gif";
+
+# CLI
+
+Cup's CLI provides the `cup check` command.
+
+## Basic Usage
+
+### Check for all updates
+```ansi
+$ cup check
+nginx:alpine                                      Update available
+redis:7                                           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
+```
+
+### Check for updates to a specific image
+```
+$ cup check node:latest
+node:latest has an update available
+```
+
+## Enable icons
+You can also enable icons if you have a [Nerd Font](https://nerdfonts.com) installed.
+
+<Image src={cup} unoptimized />
+
+## 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.
+
+```
+$ 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
+type CupData = {
+    metrics: {
+        monitored_images: number,
+        up_to_date: number,
+        update_available: number,
+        unknown: number
+    },
+    images: {
+        [image: string]: boolean | null
+    }
+}
+```
+
+## Usage with Docker
+
+If you're using the Docker image, just replace all occurences of `cup` in the examples with `docker run -tv /var/run/docker.sock:/var/run/docker.sock ghcr.io/sergi0g/cup`.
+
+For example, this:
+```bash /check node:latest/
+$ cup check node:latest
+```
+becomes:
+```bash /check node:latest/
+$ docker run -tv /var/run/docker.sock:/var/run/docker.sock ghcr.io/sergi0g/cup check node:latest
+```

docs/pages/docs/usage/server.mdx

@@ -0,0 +1,53 @@
+import { Callout } from "nextra-theme-docs";
+
+# Server
+
+The server provides the `cup serve` command.
+
+## Basic usage
+
+```ansi
+$ cup serve
+2024-07-17T09:08:38.724922Z    INFO   xitca_server::net  :  Started Tcp listening on: Some(0.0.0.0:8000)                                                                              
+2024-07-17T09:08:38.725076Z    WARN   xitca_server::server::future  :  ServerFuture::wait is called from within tokio context. It would block current thread from handling async tasks
+2024-07-17T09:08:38.725248Z    INFO   xitca_server::worker  :  Started xitca-server-worker-0                                                                                          
+2024-07-17T09:08:38.725343Z    INFO   xitca_server::worker  :  Started xitca-server-worker-1                                                                                          
+2024-07-17T09:08:38.725580Z    INFO   xitca_server::worker  :  Started xitca-server-worker-2                                                                                          
+2024-07-17T09:08:38.725607Z    INFO   xitca_server::worker  :  Started xitca-server-worker-3                                                                                          
+2024-07-17T09:08:41.390783Z    INFO   request  {  method  = GET  uri  = / }  :   on_request  :  serving request                       
+2024-07-17T09:08:41.390905Z    INFO   request  {  method  = GET  uri  = / }  :   on_response  :  sending response
+```
+
+This will launch the server on port `8000`. To access it, visit `http://<YOUR_IP>:8000` (replace `<YOUR_IP>` with the IP address of the machine running Cup.)
+
+<Callout>
+The URL `http://<YOUR_IP>:8000/json` is also available for usage with integrations.
+</Callout>
+
+## Use a different port
+
+Pass the `-p` argument with the port you want to use
+
+```ansi
+$ cup serve -p 9000
+2024-07-17T09:08:38.724922Z    INFO   xitca_server::net  :  Started Tcp listening on: Some(0.0.0.0:9000)                                                                              
+2024-07-17T09:08:38.725076Z    WARN   xitca_server::server::future  :  ServerFuture::wait is called from within tokio context. It would block current thread from handling async tasks
+2024-07-17T09:08:38.725248Z    INFO   xitca_server::worker  :  Started xitca-server-worker-0                                                                                          
+2024-07-17T09:08:38.725343Z    INFO   xitca_server::worker  :  Started xitca-server-worker-1                                                                                          
+2024-07-17T09:08:38.725580Z    INFO   xitca_server::worker  :  Started xitca-server-worker-2                                                                                          
+2024-07-17T09:08:38.725607Z    INFO   xitca_server::worker  :  Started xitca-server-worker-3                                                                                          
+2024-07-17T09:08:41.390783Z    INFO   request  {  method  = GET  uri  = / }  :   on_request  :  serving request                       
+2024-07-17T09:08:41.390905Z    INFO   request  {  method  = GET  uri  = / }  :   on_response  :  sending response
+```
+
+## Usage with Docker
+If you're using the Docker image, just replace all occurences of `cup` in the examples with `docker run -tv /var/run/docker.sock:/var/run/docker.sock -p <PORT>:<PORT> ghcr.io/sergi0g/cup`, where `<PORT>` is the port Cup will be using.
+
+For example, this:
+```bash /serve -p 9000/
+$ cup serve -p 9000
+```
+becomes:
+```bash /serve -p 9000/
+$ docker run -tv /var/run/docker.sock:/var/run/docker.sock -p 9000:9000 ghcr.io/sergi0g/cup serve -p 9000
+```