docs: readme redesign #400
Conversation
|
Warning Rate limit exceeded@raghavyuva has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 4 minutes and 22 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
WalkthroughREADME.md reworked: header replaced by a centered hero image and compact top navigation; project overview condensed; demo/screenshots simplified; inline VPS install script and detailed CLI examples removed and replaced with concise install prompts and an expanded optional flags list; Sponsors removed, Contributors retained. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
README.md (4)
111-111: Tighten grammar and punctuation in the install sentence.-You can also install the CLI and run `nixopus install` with options in a single command, refer [installation documentation](https://docs.nixopus.com/install/#installation-options) for more details on options +You can also install the CLI and run `nixopus install` with options in a single command. Refer to the [installation documentation](https://docs.nixopus.com/install/#installation-options) for details on all options.
114-118: Constrain demo image sizes and enable lazy-loading to reduce README weight.Large images in a table can bloat page load. Constrain width and add
loading="lazy".-| <a href="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/28nkmy49nm7oi5tq1t8c.webp"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/28nkmy49nm7oi5tq1t8c.webp" alt="Self Host Stats" /></a> | <a href="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gd5wei3oorzo6nwz96ro.webp"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gd5wei3oorzo6nwz96ro.webp" alt="Team Display" /></a> | <a href="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ikku6lr6cuqvv4ap5532.webp"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ikku6lr6cuqvv4ap5532.webp" alt="File Manager" /></a> | +| <a href="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/28nkmy49nm7oi5tq1t8c.webp"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/28nkmy49nm7oi5tq1t8c.webp" alt="Self Host Stats" width="360" loading="lazy" /></a> | <a href="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gd5wei3oorzo6nwz96ro.webp"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gd5wei3oorzo6nwz96ro.webp" alt="Team Display" width="360" loading="lazy" /></a> | <a href="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ikku6lr6cuqvv4ap5532.webp"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ikku6lr6cuqvv4ap5532.webp" alt="File Manager" width="360" loading="lazy" /></a> |
120-122: Apply the same sizing and lazy-load to second row of screenshots.-| <a href="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/quinawz7qvb6b5czi7u9.webp"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/quinawz7qvb6b5czi7u9.webp" alt="Self Host Logs" /></a> | <a href="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/iu7s99nj347eb24b2sdz.webp"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/iu7s99nj347eb24b2sdz.webp" alt="Dashboard Overview" /></a> | <a href="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jtcayilnk5oeyy3qmcrp.webp"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jtcayilnk5oeyy3qmcrp.webp" alt="Notification Preferences" /></a> | +| <a href="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/quinawz7qvb6b5czi7u9.webp"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/quinawz7qvb6b5czi7u9.webp" alt="Self Host Logs" width="360" loading="lazy" /></a> | <a href="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/iu7s99nj347eb24b2sdz.webp"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/iu7s99nj347eb24b2sdz.webp" alt="Dashboard Overview" width="360" loading="lazy" /></a> | <a href="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jtcayilnk5oeyy3qmcrp.webp"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jtcayilnk5oeyy3qmcrp.webp" alt="Notification Preferences" width="360" loading="lazy" /></a> |
10-12: Improve hero image accessibility and responsiveness; add lazy-loading.Replace non‑descriptive alt and fixed width/height with responsive styling; add loading="lazy" to both images. Logo file verified at ./assets/nixopus_logo_transparent.png (also present in ./view/public/).
-<img width="1210" height="796" alt="image" src="https://github.com/user-attachments/assets/5d0145b1-6d56-4de9-b05c-84e5bedd0987" /> +<img src="https://github.com/user-attachments/assets/5d0145b1-6d56-4de9-b05c-84e5bedd0987" + alt="Nixopus dashboard hero overview" + style="max-width:100%; height:auto;" + loading="lazy" /> -<a href="https://nixopus.com"><img align="right" src="./assets/nixopus_logo_transparent.png" alt="Nixopus Logo" width="250" /></a> +<a href="https://nixopus.com"><img align="right" src="./assets/nixopus_logo_transparent.png" alt="Nixopus logo" width="250" loading="lazy" style="margin-left:12px;" /></a>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (7)
README.md (7)
1-2: Improve hero image accessibility; consider adding an H1 for SEO/ATs
- Alt text "Heading(2)" is non-descriptive.
- Fixed pixel width/height are unnecessary; rely on GitHub’s responsive styling and add lazy loading.
Apply:
- <img width="1800" height="520" alt="Heading(2)" src="https://github.com/user-attachments/assets/fa7ddf17-1062-4987-bead-e23fc8655ad3" /> + <img alt="Nixopus — open-source server management platform" src="https://github.com/user-attachments/assets/fa7ddf17-1062-4987-bead-e23fc8655ad3" loading="lazy" />Additionally, add a top-level heading immediately after the hero block:
# Nixopus
6-8: Tighten tagline wording and casingUse consistent casing for “open source” and “self-hosting”; remove extra capitalization.
- Open Source server management platform with Docker support, terminal integration, and Self Hosting capabilities. + Open‑source server management platform with Docker support, terminal integration, and self‑hosting capabilities.
10-15: Stabilize external links and expand nav
- Discord invites can expire; consider a docs-domain redirect (e.g., /discord) you can rotate behind the scenes.
- Optional: add a GitHub repo link for quick access.
17-17: Screenshot: add descriptive alt and lazy loadingAlt="image" isn’t helpful for screen readers.
-<img width="1210" height="764" alt="image" src="https://github.com/user-attachments/assets/3f1dc1e0-956d-4785-8745-ed59d0390afd" /> +<img alt="Nixopus dashboard overview" src="https://github.com/user-attachments/assets/3f1dc1e0-956d-4785-8745-ed59d0390afd" loading="lazy" />
20-20: Time-bound the alpha disclaimerAdd “as of September 2025” so readers can assess freshness later.
-> ⚠️ **Important Note**: Nixopus is currently in alpha/pre-release stage and is not yet ready for production use. While you're welcome to try it out, we recommend waiting for the beta or stable release before using it in production environments. The platform is still undergoing testing and development. +> ⚠️ **Important Note** (as of September 2025): Nixopus is in alpha/pre‑release and not ready for production. You’re welcome to try it out, but consider waiting for a beta or stable release. The platform is still undergoing testing and development.
72-72: Grammar/punctuation fix for sentence clarity-You can also install the CLI and run `nixopus install` with options in a single command, refer [installation documentation](https://docs.nixopus.com/install/#installation-options) for more details on options +You can also install the CLI and run `nixopus install` with options in a single command. Refer to the [installation documentation](https://docs.nixopus.com/install/#installation-options) for details on all options.
75-83: Screenshots table: minor polish
- Remove the extra space before “Notification Preferences”.
- Optional: host images in-repo to avoid third-party hotlinking risk.
-| Self Host Logs | Dashboard Overview | Notification Preferences | +| Self Host Logs | Dashboard Overview | Notification Preferences |
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(2 hunks)
🔇 Additional comments (2)
README.md (2)
85-88: “About the Name” reads wellContent is clear and non-misleading. No action needed.
60-60: Incorrect — no change needed; the raw URL is validBoth the original raw URL using refs/heads/master and the alternative with /master return the same file contents (no 404 observed). (raw.githubusercontent.com)
Likely an incorrect or invalid review comment.
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
README.md (1)
35-49: curl | bash installer: add integrity guidance and a versioned path.Piping remote scripts to bash is unsafe — add explicit checksum/signature verification instructions and a versioned release install URL for one-liners.
- Confirmed: README.md (lines 41–47) contains the one-liner; scripts/install.sh documents the --skip-nixopus-install flag (scripts/install.sh:50). Update README.md, docs/install/index.md and examples to show verification and a pinned release URL.
-curl -sSL https://install.nixopus.com | bash +# Prefer verifying before executing: +# 1) Inspect the script: +# curl -fsSL https://install.nixopus.com/install.sh -o install.sh +# 2) Verify checksum/signature (publish checksum and/or GPG signature in repo/docs). +# 3) Run: +# bash install.sh + +# For a one-liner, pin to a release tag: +curl -fsSL https://install.nixopus.com/releases/vX.Y.Z/install.sh | bash
🧹 Nitpick comments (10)
README.md (10)
1-3: Make hero image responsive and improve alt text.Fixed width/height harms mobile rendering and the alt is non-descriptive. Prefer max-width with auto height and a meaningful alt.
-<div align="center"> - <img width="1800" height="520" alt="Heading(2)" src="https://github.com/user-attachments/assets/fa7ddf17-1062-4987-bead-e23fc8655ad3" /> -</div> +<div align="center"> + <img alt="Nixopus — open-source server management platform" src="https://github.com/user-attachments/assets/fa7ddf17-1062-4987-bead-e23fc8655ad3" style="max-width:100%; height:auto;" /> +</div>
6-8: Tighten tagline phrasing.Use “self‑hosting” and drop title case mid-sentence.
- Open Source server management platform with Docker support, terminal integration, and Self Hosting capabilities. + Open-source server management platform with Docker support, terminal integration, and self‑hosting capabilities.
17-18: Second large image: same responsiveness/alt issues.-<img width="1210" height="764" alt="image" src="https://github.com/user-attachments/assets/3f1dc1e0-956d-4785-8745-ed59d0390afd" /> +<img alt="Nixopus dashboard preview" src="https://github.com/user-attachments/assets/3f1dc1e0-956d-4785-8745-ed59d0390afd" style="max-width:100%; height:auto;" />
20-20: Surface the alpha warning earlier.Consider moving this block right below the hero/tagline so readers see it before installation.
50-61: Options: document defaults/requirements and pin config link.
- Note defaults (where applicable) and whether sudo/root is required.
- Pin
config.prod.yamllink to a commit to avoid “moving master”.-- `--timeout` or `-t`: Set timeout for each step (default: 300 seconds) +- `--timeout` or `-t`: Set timeout for each step (default: 300s) +- Requires sudo/root for installation steps that modify system services. -- `--config-file` or `-c`: Path to custom config file (defaults to built-in [`config.prod.yaml`](https://raw.githubusercontent.com/raghavyuva/nixopus/refs/heads/master/helpers/config.prod.yaml)) +- `--config-file` or `-c`: Path to custom config file (defaults to built-in [`config.prod.yaml`](https://raw.githubusercontent.com/raghavyuva/nixopus/<commit-sha>/helpers/config.prod.yaml))Please confirm all short flags (
-ad,-vd,-v,-t,-f,-d,-c) match the CLI parser.
64-70: Clarify context fornixopus install.Explicitly state this requires the CLI to be installed and show
sudoif necessary.-```bash -nixopus install \ +```bash +# Requires the Nixopus CLI to be installed (see above). Use sudo if your environment requires it: +sudo nixopus install \
72-72: Grammar/punctuation fix and make the call-to-action clearer.-You can also install the CLI and run `nixopus install` with options in a single command, refer [installation documentation](https://docs.nixopus.com/install/#installation-options) for more details on options +You can also install the CLI and run `nixopus install` with options in a single command. Refer to the [installation documentation](https://docs.nixopus.com/install/#installation-options) for details.
75-83: Screenshots hosting and accessibility.
- Third‑party image hosts can break; consider storing assets in-repo.
- Add explicit widths or rely on GitHub’s responsive styling to prevent layout overflow; current HTML-less Markdown will auto-scale, so you’re likely fine.
- Alt text is good—keep it descriptive.
24-31: Feature bullets: minor consistency nits.Keep punctuation consistent (either all with periods or none) and consider naming “Caddy” in the SSL bullet for clarity since you reference it below.
-- **Auto SSL certificates.** Your domains get HTTPS automatically. +- **Automatic TLS certificates.** Your domains get HTTPS automatically (via Caddy).
10-15: Automate link/flag verification in CI (optional).We can add a lightweight check to prevent broken links and flag drift between README and CLI.
If you want, I can open a follow-up PR wiring:
- lychee link checker (docs/blog/discord/installer/config links)
- a script that diffs README-listed flags vs. the CLI parser output
Also applies to: 35-70
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(2 hunks)
🔇 Additional comments (1)
README.md (1)
10-15: Verify external links and consider consistent wording.Sanity-check that Website/Docs/Blog/Discord URLs are correct and stable. Also, “Blog” lives under docs—confirm that’s intentional.
Would you like a quick link check script added to CI to catch future 404s?
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
README.md (1)
39-48: Avoid curl | bash; provide verification (checksum/signature) and least-privilege executionPiping install scripts directly to a shell is a common supply-chain risk. Offer a safer flow: download, verify, then execute (with sudo only when required).
-```bash -curl -sSL https://install.nixopus.com | bash -``` +```bash +# Download installer and checksum +curl -fsSLo nixopus-install.sh https://install.nixopus.com/install.sh +curl -fsSLo nixopus-install.sh.sha256 https://install.nixopus.com/install.sh.sha256 +# Verify integrity (expect: OK) +sha256sum -c nixopus-install.sh.sha256 +# Run installer (add sudo only if needed) +bash nixopus-install.sh +```And for the CLI-only path:
-```bash -curl -sSL https://install.nixopus.com | bash -s -- --skip-nixopus-install -``` +```bash +bash nixopus-install.sh --skip-nixopus-install +```If you already publish signatures, link to the public key and show a
gpg --verifystep too. I can draft that section if you share the signing details.
🧹 Nitpick comments (8)
README.md (8)
1-2: Improve hero image accessibility and resilience
- Alt text “Heading(2)” is non-descriptive. Use a concise, meaningful description.
- Consider hosting the asset in-repo (e.g., under docs/assets/) and linking via a permalink to avoid user-attachments link rot.
Apply:
- <img width="1800" height="520" alt="Heading(2)" src="https://github.com/user-attachments/assets/fa7ddf17-1062-4987-bead-e23fc8655ad3" /> + <img width="1800" height="520" alt="Nixopus hero banner showcasing dashboard" src="docs/assets/hero-banner.png" />
17-17: Screenshot alt text is too genericReplace “image” with a descriptive alt that conveys the content for screen readers.
-<img width="1210" height="764" alt="image" src="https://github.com/user-attachments/assets/3f1dc1e0-956d-4785-8745-ed59d0390afd" /> +<img width="1210" height="764" alt="Nixopus app overview: server list, resource graphs, and actions" src="docs/assets/app-overview.png" />
20-20: Alpha note: add pointer to roadmap/issuesA direct link helps users track readiness and known limitations.
-> ⚠️ **Important Note**: Nixopus is currently in alpha/pre-release stage and is not yet ready for production use. While you're welcome to try it out, we recommend waiting for the beta or stable release before using it in production environments. The platform is still undergoing testing and development. +> ⚠️ **Important Note**: Nixopus is in alpha/pre-release and not ready for production. You’re welcome to try it out, but consider waiting for beta or stable before production use. Track progress and known issues on the [roadmap](https://docs.nixopus.com/roadmap/) and [issue tracker](https://github.com/raghavyuva/nixopus/issues).
54-61: Fix raw GitHub URL format and pin to a tag/commitThe current raw URL uses “refs/heads/master”, which is non-standard and brittle. Prefer a tag/commit permalink or at least the branch form below.
-- `--config-file` or `-c`: Path to custom config file (defaults to built-in [`config.prod.yaml`](https://raw.githubusercontent.com/raghavyuva/nixopus/refs/heads/master/helpers/config.prod.yaml)) +- `--config-file` or `-c`: Path to custom config file (defaults to built-in [`config.prod.yaml`](https://raw.githubusercontent.com/raghavyuva/nixopus/master/helpers/config.prod.yaml))Even better (pin to a release/tag):
https://raw.githubusercontent.com/raghavyuva/nixopus/vX.Y.Z/helpers/config.prod.yaml
24-31: Set expectations for Features that require prerequisites
- Auto SSL: clarify DNS/80/443 requirements and any Cloudflare/ACME caveats.
- GitHub integration: list required token scopes and where to configure them.
65-70: CLI example: include one advanced flag for discoverabilityConsider adding one of the optional flags (e.g., --config-file) so users see how to pass values that include paths.
nixopus install \ --api-domain nixopusapi.example.tld \ --view-domain nixopus.example.tld \ --verbose \ - --timeout 600 + --timeout 600 \ + --config-file /etc/nixopus/config.prod.yaml
72-72: Grammar and punctuationTighten the sentence and add a period.
-You can also install the CLI and run `nixopus install` with options in a single command, refer [installation documentation](https://docs.nixopus.com/install/#installation-options) for more details on options +You can also install the CLI and run `nixopus install` with options in a single command. Refer to the [installation documentation](https://docs.nixopus.com/install/#installation-options) for details on all options.
6-15: External nav links verified; add docs "Install" anchorLocation: README.md (lines 6–15). nixopus.com, docs.nixopus.com, and docs.nixopus.com/blog return 200; discord.gg/skdcq39Wpv returns 301 (redirect). Add or deep-link to an "Install" section/page in the docs to improve onboarding.
Summary by CodeRabbit