From ed17c3ad3e16a9c3e605fa8d672f89d39fb630a5 Mon Sep 17 00:00:00 2001 From: Cole Manel Date: Fri, 19 Sep 2025 15:48:47 -0400 Subject: [PATCH 1/4] setup getting started --- .vscode/settings.json | 44 ++++++++-------- docs/.vitepress/nav.ts | 2 +- docs/.vitepress/sidebar.ts | 12 ++++- .../installation}/InstallGuide.md | 0 docs/getting-started/overview.md | 52 +++++++++++++++++++ docs/getting-started/setup/CompleteSetup.md | 6 +++ docs/index.md | 3 +- 7 files changed, 94 insertions(+), 25 deletions(-) rename docs/{ => getting-started/installation}/InstallGuide.md (100%) create mode 100644 docs/getting-started/overview.md create mode 100644 docs/getting-started/setup/CompleteSetup.md diff --git a/.vscode/settings.json b/.vscode/settings.json index 73cc51c2..6a6257e2 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,22 +1,22 @@ -{ - "workbench.colorCustomizations": { - "activityBar.activeBackground": "#b6bdbf", - "activityBar.background": "#b6bdbf", - "activityBar.foreground": "#15202b", - "activityBar.inactiveForeground": "#15202b99", - "activityBarBadge.background": "#c758ae", - "activityBarBadge.foreground": "#15202b", - "commandCenter.border": "#15202b99", - "sash.hoverBorder": "#b6bdbf", - "statusBar.background": "#9ba4a7", - "statusBar.foreground": "#15202b", - "statusBarItem.hoverBackground": "#808b8f", - "statusBarItem.remoteBackground": "#9ba4a7", - "statusBarItem.remoteForeground": "#15202b", - "titleBar.activeBackground": "#9ba4a7", - "titleBar.activeForeground": "#15202b", - "titleBar.inactiveBackground": "#9ba4a799", - "titleBar.inactiveForeground": "#15202b99" - }, - "peacock.color": "#9ba4a7" -} \ No newline at end of file +// { +// "workbench.colorCustomizations": { +// "activityBar.activeBackground": "#b6bdbf", +// "activityBar.background": "#b6bdbf", +// "activityBar.foreground": "#15202b", +// "activityBar.inactiveForeground": "#15202b99", +// "activityBarBadge.background": "#c758ae", +// "activityBarBadge.foreground": "#15202b", +// "commandCenter.border": "#15202b99", +// "sash.hoverBorder": "#b6bdbf", +// "statusBar.background": "#9ba4a7", +// "statusBar.foreground": "#15202b", +// "statusBarItem.hoverBackground": "#808b8f", +// "statusBarItem.remoteBackground": "#9ba4a7", +// "statusBarItem.remoteForeground": "#15202b", +// "titleBar.activeBackground": "#9ba4a7", +// "titleBar.activeForeground": "#15202b", +// "titleBar.inactiveBackground": "#9ba4a799", +// "titleBar.inactiveForeground": "#15202b99" +// }, +// // "peacock.color": "#9ba4a7" +// } \ No newline at end of file diff --git a/docs/.vitepress/nav.ts b/docs/.vitepress/nav.ts index 244417ec..ec6d8660 100644 --- a/docs/.vitepress/nav.ts +++ b/docs/.vitepress/nav.ts @@ -3,7 +3,7 @@ import type { DefaultTheme } from 'vitepress' const nav: DefaultTheme.NavItem[] = [ { text: 'Home', link: '/' }, { text: 'Install Scripts', link: '/install-scripts/overview' }, - + { text: 'Getting Started', link: '/getting-started/overview' }, ] export default nav diff --git a/docs/.vitepress/sidebar.ts b/docs/.vitepress/sidebar.ts index 244558bc..50fcaba9 100644 --- a/docs/.vitepress/sidebar.ts +++ b/docs/.vitepress/sidebar.ts @@ -14,12 +14,22 @@ const sidebar: DefaultTheme.Sidebar = { ] } ], + '/getting-started/': [ + { + text: 'Getting Started', + items: [ + { text: 'Overview', link: '/getting-started/overview' }, + { text: 'Install HexOS', link: '/getting-started/installation/InstallGuide' }, + ] + } + ], '/': [ { text: 'Documentation', items: [ { text: 'Home', link: '/' }, - { text: 'Install Scripts', link: '/install-scripts/overview' } + { text: 'Install Scripts', link: '/install-scripts/overview' }, + { text: 'Getting Started', link: '/getting-started/overview' } ] } ] diff --git a/docs/InstallGuide.md b/docs/getting-started/installation/InstallGuide.md similarity index 100% rename from docs/InstallGuide.md rename to docs/getting-started/installation/InstallGuide.md diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md new file mode 100644 index 00000000..acccda34 --- /dev/null +++ b/docs/getting-started/overview.md @@ -0,0 +1,52 @@ +# Getting Started + +Congratulations on taking the first step on your journey towards digital self-reliance and self-hosting. This article will guide you to getting HexOS installed and set up on your home server. + +## System Requirements + +For basic storage and folder capabilities, HexOS has the same underlying system requirements as TrueNAS SCALE: + +- Processor: 2-Core Intel 64-Bit or AMD x86_64 processor +- Memory: 8 GB memory +- Boot Device: 16 GB SSD boot device +- Storage: + - One storage device for testing purposes* + - Two storage devices for a mirrored pool** + - Three storage devices for an expandable pool + +\* *single device configurations offer no redundancy and should only be used for test/dev purposes* +** *mirrored pools cannot be expanded by adding additional storage devices* + +However, the applications you intend to deploy can significantly increase these requirements. Consult documentation of the applications you intend to install for their respective recommendations. + +## Get Yourself a Server + +When it comes to the physical hardware itself, you have two choices: bring your own or buy something pre-built (OEM). + +### Bring-Your-Own-Hardware (BYOH) + +Have an old PC or gaming rig laying around? Can you get your hands on a decommissioned or refurbished server? Want to build something new? One of the beautiful things about HexOS and Linux is the ability to use just about any capable hardware and turn it into a home server. This is an ideal path for technology enthusiasts and IT professionals. DIY approaches do require a bit of technical aptitude and light reading, as hardware selection is important. Thankfully, TrueNAS provides a [comprehensive hardware guide](https://www.truenas.com/docs/scale/gettingstarted/scalehardwareguide/) that covers all aspects of selecting your gear including minimum system requirements, storage devices/controllers, etc. You can also introduce yourself to our community in the forum for further guidance and support on your setup. + +### Buy Pre-Built + +There are many OEM NAS appliance vendors available for purchase in the hardware market. However, for the best support, TrueNAS servers including their Mini-R series are constantly tested to ensure solid support with SCALE and HexOS. For non-TrueNAS based systems, seek community guidance and avoid proprietary hardware vendors like Synology/QNAP. + +## Get Yourself Some Storage + +Selecting storage devices for your home server comes down to your capacity requirements, performance expectations, and hardware capabilities. HDDs should be used for user data and SSDs can offer faster speeds for high-performance applications and use-cases. + +### Recommended Layouts + +While you can ultimately create as many pools in whatever configurations you want using HexOS, most users will benefit from one of three primary configurations. + +#### The Minimalist + +Technically all features of HexOS can be achieved with a single pool. Both data you and your apps create will live in the same pool of storage. If users, applications, and performance expectations are all low, HDDs are fine. Otherwise, SSDs may be preferred, though the price per TB is higher. Just remember to start with a minimum of 3 devices so that you can expand as you grow. If you want the best of both worlds and better scalability, see the next layout. + +#### The Enthusiast + +If both HDD and SSD pools are available, HexOS will automatically optimize their usage with folders, applications, and in the future, virtual machines. This will result in improved application performance and storage efficiency. While we highly recommend a minimum of three storage devices for the HDD pool, a two-device SSD pool can be acceptable. Consider your total expandability (storage ports) in your system when deciding on pool widths. + +#### The Professional + +For the tech savvy IT admin or developer who wants more granular control over their storage configuration, HexOS also supports the use of TrueNAS-managed pools. Simply create your storage pool via TrueNAS and it will appear as an option when configuring HexOS features like folders and apps. HexOS will generate relevant alerts/notifications for pool issues including device failures and aggressive SMART errors. However, all storage management operations (expansion, disk replacement, etc.) will need to be performed through the TrueNAS UI. diff --git a/docs/getting-started/setup/CompleteSetup.md b/docs/getting-started/setup/CompleteSetup.md new file mode 100644 index 00000000..82c073ee --- /dev/null +++ b/docs/getting-started/setup/CompleteSetup.md @@ -0,0 +1,6 @@ +# Complete Setup + +deck.hexos.com login +Claiming your server +Health and capabilities +Storage configuration diff --git a/docs/index.md b/docs/index.md index fd34496c..c5394dec 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,4 @@ # HexOS Docs -Welcome! This site documents some of how HexOS works and specific guides for advanced usage. \ No newline at end of file +The HexOS Docs site is designed to help users on their journey to self-hosting a home server. The documentation herein is a work in progress and will continue to evolve over time. Users that wish to write new guides or submit edits to these docs, please see the section on Community Contributions. + From a1b94b5587009d7db0c2d4c730d8bbe649608075 Mon Sep 17 00:00:00 2001 From: Cole Manel Date: Tue, 23 Sep 2025 12:38:18 -0400 Subject: [PATCH 2/4] bump --- docs/.vitepress/nav.ts | 1 + docs/.vitepress/sidebar.ts | 16 ++++- docs/features/overview.md | 21 +++++++ .../installation/InstallGuide.md | 2 +- docs/getting-started/setup/CompleteSetup.md | 59 +++++++++++++++++-- 5 files changed, 92 insertions(+), 7 deletions(-) create mode 100644 docs/features/overview.md diff --git a/docs/.vitepress/nav.ts b/docs/.vitepress/nav.ts index ec6d8660..7447ae9c 100644 --- a/docs/.vitepress/nav.ts +++ b/docs/.vitepress/nav.ts @@ -4,6 +4,7 @@ const nav: DefaultTheme.NavItem[] = [ { text: 'Home', link: '/' }, { text: 'Install Scripts', link: '/install-scripts/overview' }, { text: 'Getting Started', link: '/getting-started/overview' }, + { text: 'Features', link: '/features/overview' }, ] export default nav diff --git a/docs/.vitepress/sidebar.ts b/docs/.vitepress/sidebar.ts index 50fcaba9..2de32799 100644 --- a/docs/.vitepress/sidebar.ts +++ b/docs/.vitepress/sidebar.ts @@ -20,16 +20,30 @@ const sidebar: DefaultTheme.Sidebar = { items: [ { text: 'Overview', link: '/getting-started/overview' }, { text: 'Install HexOS', link: '/getting-started/installation/InstallGuide' }, + { text: 'Complete Setup', link: '/getting-started/setup/CompleteSetup' }, ] } ], + '/features/': [ + { + text: 'Features', + items: [ + { text: 'Overview', link: '/features/overview' }, + { text: 'Storage', link: '/features/storage' }, + { text: 'Files', link: '/features/folders' }, + { text: 'Apps', link: '/features/apps' }, + { text: 'Settings', link: '/features/settings' }, + ], + } + ], '/': [ { text: 'Documentation', items: [ { text: 'Home', link: '/' }, { text: 'Install Scripts', link: '/install-scripts/overview' }, - { text: 'Getting Started', link: '/getting-started/overview' } + { text: 'Getting Started', link: '/getting-started/overview' }, + { text: 'Features', link: '/features/overview' }, ] } ] diff --git a/docs/features/overview.md b/docs/features/overview.md new file mode 100644 index 00000000..82d82363 --- /dev/null +++ b/docs/features/overview.md @@ -0,0 +1,21 @@ +# Features + +some text that gives an introduction to what all the features encompass. + +## Dashboard + +Immediately after completing the setup wizard, you will be first taken to the HexOS Dashboard. From here, you can review system activities, apply OS updates, monitor resource usage, and control your installed applications/virtual machines. + +By default you will see information on your system, (activity messages, hardware information) storage, and apps. However this display is configurable in [setttings]. + +## Notifications + +HexOS provides notifications to users in two primary ways: +- All notifications are delivered to the HexOS “Bell” icon, visible on all pages. +- Critical notifications (e.g. disk failures) are also delivered automatically to you via email. + +Notifications can be both marked as read and dismissed, and previous notifications can be viewed from within the messaging archive. + +## Profile + +Your user profile is also available on all pages of HexOS, where you can toggle dark mode, launch the Community Hub, give feedback to us, or logout. diff --git a/docs/getting-started/installation/InstallGuide.md b/docs/getting-started/installation/InstallGuide.md index c1c935d8..14682ac9 100644 --- a/docs/getting-started/installation/InstallGuide.md +++ b/docs/getting-started/installation/InstallGuide.md @@ -45,7 +45,7 @@ - [![Capture5.PNG.f7af55f85dc45fff3932704006737410.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture5.PNG.f7af55f85dc45fff3932704006737410.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture5.PNG.f7af55f85dc45fff3932704006737410.PNG "Enlarge image") - Next we need to set the root password for the TrueNAS install that underpins HexOS. - - Be sure not to loose this, you will need it later when adopting your server on Deck.HexOS.com + - Be sure not to lose this, you will need it later when adopting your server on Deck.HexOS.com - **\*NOTE\*: If you use a NON US KEYBOARD please be cautious about special characters, as the installer defaults to a US keyboard layout!** - _[See this comment for details.](https://hub.hexos.com/topic/103-illustrated-installation-guide-start-here/page/2/#findComment-8073)_ - [![Capture6.PNG.2757a99cb3d6eff2456fae08f5d8af22.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture6.PNG.2757a99cb3d6eff2456fae08f5d8af22.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture6.PNG.2757a99cb3d6eff2456fae08f5d8af22.PNG "Enlarge image") diff --git a/docs/getting-started/setup/CompleteSetup.md b/docs/getting-started/setup/CompleteSetup.md index 82c073ee..fab0f5df 100644 --- a/docs/getting-started/setup/CompleteSetup.md +++ b/docs/getting-started/setup/CompleteSetup.md @@ -1,6 +1,55 @@ -# Complete Setup +# Complete Server Setup + +Now that HexOS is installed, you’re almost ready to set up your server! +Before beginning the setup process, there are a couple of things you’ll need to do first. + +### Login to HexOS + +Using your HexOS login, access the HexOS command deck at [deck.hexos.com](https://deck.hexos.com). + +If you have not already signed up you can [sign up](https://hub.hexos.com/register/) here. + +### Claiming Your Server + +Once logged in, you'll need to claim your server. + +Your server should appear in the right panel where it says "Looking for servers...". +Claiming it will require the password you used during the installation process for HexOS. + +#### Server Not Showing Up? + +Is your server not showing up? Don't worry just yet. You may need to connect manually. +- Click the "Having Problems" link, followed by "enter your ip manually". +- Enter your WAN IP address (if you are unsure what that is you can find yours [here](https://whatismyipaddress.com/)). + +Once entered, your server should appear and can be claimed. + +## Server Setup Process + +### Step 1: Health and Capabilities + +After claiming, you'll be brought to a display containing all of your server's hardware. +Make sure you see the correct number of drives and that no errors are being displayed. +If you see lots of green checks, you're good to go! + +### Step 2: Storage Pools + +HexOS will suggest a storage pool layout based on your hardware. +For most people, the recommended configuration is the best path forward. + +If you are more of a tinkerer you can remove drives from default pools, or skip pool creation and manually configure later. + +Keep in mind removing drives can reduce redundancy and affect how safely your pools handle failures. Not having enough drives in a pool will also affect your ability to add more drives to the pool later on. + +### Step 3: Verification & Server Naming + +Complete your setup by verifying everything is working correctly. +Your pools should reflect the settings you went forward with inside of pool configuration. + +Finally, give your server a name and your server is good to go! + +### What's Next? + +Your server will finish initializing momentarily and bring you to the dashboard. +From here you can explore all of HexOS's features, check out our [Features Guide] to learn more! -deck.hexos.com login -Claiming your server -Health and capabilities -Storage configuration From d6fa07be6692034d14988e3a6cddee5d8fe200c3 Mon Sep 17 00:00:00 2001 From: Cole Manel Date: Wed, 24 Sep 2025 11:37:17 -0400 Subject: [PATCH 3/4] first draft, troubleshooting, community wip --- docs/.vitepress/nav.ts | 6 +- docs/.vitepress/sidebar.ts | 67 +++++++++++------ docs/community/index.md | 23 ++++++ docs/features/apps/index.md | 24 +++++++ .../install-scripts/advanced/debugging.md | 0 .../apps/install-scripts/contributing.md | 10 +++ .../apps}/install-scripts/curated/index.md | 0 .../apps}/install-scripts/overview.md | 0 .../apps}/install-scripts/reference/macros.md | 0 .../apps}/install-scripts/reference/schema.md | 0 docs/features/folders/index.md | 47 ++++++++++++ docs/features/index.md | 24 +++++++ docs/features/notifications/index.md | 29 ++++++++ docs/features/overview.md | 21 ------ .../settings/experimental-features/index.md | 11 +++ docs/features/settings/index.md | 23 ++++++ docs/features/storage/storage.md | 40 +++++++++++ docs/install-scripts/contributing.md | 9 --- docs/licensing/index.md | 9 +++ docs/troubleshooting/index.md | 71 +++++++++++++++++++ 20 files changed, 362 insertions(+), 52 deletions(-) create mode 100644 docs/community/index.md create mode 100644 docs/features/apps/index.md rename docs/{ => features/apps}/install-scripts/advanced/debugging.md (100%) create mode 100644 docs/features/apps/install-scripts/contributing.md rename docs/{ => features/apps}/install-scripts/curated/index.md (100%) rename docs/{ => features/apps}/install-scripts/overview.md (100%) rename docs/{ => features/apps}/install-scripts/reference/macros.md (100%) rename docs/{ => features/apps}/install-scripts/reference/schema.md (100%) create mode 100644 docs/features/folders/index.md create mode 100644 docs/features/index.md create mode 100644 docs/features/notifications/index.md delete mode 100644 docs/features/overview.md create mode 100644 docs/features/settings/experimental-features/index.md create mode 100644 docs/features/settings/index.md create mode 100644 docs/features/storage/storage.md delete mode 100644 docs/install-scripts/contributing.md create mode 100644 docs/licensing/index.md create mode 100644 docs/troubleshooting/index.md diff --git a/docs/.vitepress/nav.ts b/docs/.vitepress/nav.ts index 7447ae9c..2fba6ab9 100644 --- a/docs/.vitepress/nav.ts +++ b/docs/.vitepress/nav.ts @@ -2,9 +2,11 @@ import type { DefaultTheme } from 'vitepress' const nav: DefaultTheme.NavItem[] = [ { text: 'Home', link: '/' }, - { text: 'Install Scripts', link: '/install-scripts/overview' }, { text: 'Getting Started', link: '/getting-started/overview' }, - { text: 'Features', link: '/features/overview' }, + { text: 'Features', link: '/features/' }, + { text: 'Troubleshooting', link: '/troubleshooting/' }, + { text: 'Community', link: '/community/' }, + { text: 'Licensing', link: '/licensing/' }, ] export default nav diff --git a/docs/.vitepress/sidebar.ts b/docs/.vitepress/sidebar.ts index 2de32799..77fbce28 100644 --- a/docs/.vitepress/sidebar.ts +++ b/docs/.vitepress/sidebar.ts @@ -1,19 +1,6 @@ import type { DefaultTheme } from 'vitepress' const sidebar: DefaultTheme.Sidebar = { - '/install-scripts/': [ - { - text: 'Install Scripts', - items: [ - { text: 'Overview', link: '/install-scripts/overview' }, - { text: 'Apps (Curated Scripts)', link: '/install-scripts/curated/' }, - { text: 'Contributing', link: '/install-scripts/contributing' }, - { text: 'Reference: Schema', link: '/install-scripts/reference/schema' }, - { text: 'Reference: Macros', link: '/install-scripts/reference/macros' }, - { text: 'Advanced: Debugging', link: '/install-scripts/advanced/debugging' }, - ] - } - ], '/getting-started/': [ { text: 'Getting Started', @@ -28,22 +15,62 @@ const sidebar: DefaultTheme.Sidebar = { { text: 'Features', items: [ - { text: 'Overview', link: '/features/overview' }, - { text: 'Storage', link: '/features/storage' }, - { text: 'Files', link: '/features/folders' }, - { text: 'Apps', link: '/features/apps' }, - { text: 'Settings', link: '/features/settings' }, + { text: 'Overview', link: '/features/' }, + { text: 'Storage', link: '/features/storage/storage' }, + { text: 'Folders', link: '/features/folders/' }, + { text: 'Apps', link: '/features/apps/', + items: [ + { text: 'Install Scripts Overview', link: '/features/apps/install-scripts/overview' }, + { text: 'Curated Scripts', link: '/features/apps/install-scripts/curated/' }, + { text: 'Contributing', link: '/features/apps/install-scripts/contributing' }, + { text: 'Schema Reference', link: '/features/apps/install-scripts/reference/schema' }, + { text: 'Macros Reference', link: '/features/apps/install-scripts/reference/macros' }, + { text: 'Debugging', link: '/features/apps/install-scripts/advanced/debugging' }, + ] + }, + { text: 'Notifications', link: '/features/notifications/' }, + { text: 'Settings', link: '/features/settings/', + items: [ + { text: 'Experimental Features', link: '/features/settings/experimental-features/' }, + ] + }, ], } ], + '/troubleshooting/': [ + { + text: 'Troubleshooting', + items: [ + { text: 'Common Issues', link: '/troubleshooting/' }, + ] + } + ], + '/community/': [ + { + text: 'Community', + items: [ + { text: 'How to Contribute', link: '/community/' }, + ] + } + ], + '/licensing/': [ + { + text: 'Licensing', + items: [ + { text: 'Usage Rights', link: '/licensing/' }, + ] + } + ], '/': [ { text: 'Documentation', items: [ { text: 'Home', link: '/' }, - { text: 'Install Scripts', link: '/install-scripts/overview' }, { text: 'Getting Started', link: '/getting-started/overview' }, - { text: 'Features', link: '/features/overview' }, + { text: 'Features', link: '/features/' }, + { text: 'Troubleshooting', link: '/troubleshooting/' }, + { text: 'Community', link: '/community/' }, + { text: 'Licensing', link: '/licensing/' }, ] } ] diff --git a/docs/community/index.md b/docs/community/index.md new file mode 100644 index 00000000..6011a2e6 --- /dev/null +++ b/docs/community/index.md @@ -0,0 +1,23 @@ +# Community Contributions + +HexOS grows stronger with community involvement. Whether you're a developer, writer, or enthusiast, there are many ways to contribute to the project and help other users. + +## Help Curate Applications (Install Scripts) + +One of the most valuable contributions is helping expand the available applications. You can test existing community scripts and provide feedback, create install scripts for new applications, improve documentation with setup guides and troubleshooting tips, or help review submissions for quality and compatibility. + +## Write and Submit Code + +Developers can contribute directly to the HexOS codebase by fixing bugs, enhancing existing features, optimizing performance, or adding automated tests. The process involves forking the repository, making your changes, and submitting a pull request for review by the HexOS team. + +## Improve Our Documentation + +Documentation improvements are always welcome. Fix errors and outdated information, fill gaps for missing features, rewrite confusing sections to be clearer, or add real-world examples and use cases. Documentation contributions follow the same pull request process as code. + +## Support Other Users + +Help build a supportive community on our forums and Reddit. Share your knowledge to solve problems, post working configurations for common setups, help debug tricky issues, and welcome newcomers to make the community friendly for new users. + +## Apply to be a Moderator + +Experienced community members can apply to help moderate forums and maintain a positive environment. This involves community leadership, content moderation, conflict resolution, and helping the community grow. Applications are reviewed based on community involvement, technical knowledge, and communication skills. \ No newline at end of file diff --git a/docs/features/apps/index.md b/docs/features/apps/index.md new file mode 100644 index 00000000..0c5a5dc2 --- /dev/null +++ b/docs/features/apps/index.md @@ -0,0 +1,24 @@ +# Apps + +This is where all your applications live. You can install curated apps with one click, use community contributions, create custom installs, or go through the full TrueNAS catalog. + +## Eshtek Curations + +The HexOS team has created curated install scripts that handle all the configuration automatically, so you just click install and everything works. Over time we will continue to expand the curated section even further. + +## Community Curations + +Community members can contribute app curations to expand what's available beyond the official catalog. If there's an app you want but don't see a curation for it, you can make one yourself. + +*(I imagine we should talk about the process of adding their curations?)* + +## Install Scripts + +For non-curated apps, you can use custom install scripts to get them running. You can also view and modify the install scripts to fit your specific needs. +This requires enabling [experimental features](/features/settings/#preferences) in your preferences. + +Learn more about [install scripts](/features/apps/install-scripts/overview). + +## TrueNAS Catalog + +For advanced users who want access to everything, the full TrueNAS app catalog gives you hundreds of applications with complete control over their configuration. You're on your own for setup and troubleshooting, but you get maximum flexibility. \ No newline at end of file diff --git a/docs/install-scripts/advanced/debugging.md b/docs/features/apps/install-scripts/advanced/debugging.md similarity index 100% rename from docs/install-scripts/advanced/debugging.md rename to docs/features/apps/install-scripts/advanced/debugging.md diff --git a/docs/features/apps/install-scripts/contributing.md b/docs/features/apps/install-scripts/contributing.md new file mode 100644 index 00000000..3e1ae316 --- /dev/null +++ b/docs/features/apps/install-scripts/contributing.md @@ -0,0 +1,10 @@ +# Contributing a new app + +Want to add your app curation to the official HexOS catalog? Follow these steps to contribute your install script, or share it in our forums first to get community feedback: + +1. Test your custom curation in HexOS and verify it works reliably +2. Click [Here](https://github.com/eshtek/hexos-docs/new/main/docs/public/install-scripts) to start the contribution process +3. Click the green "Fork this repository" button +4. Paste the contents of your install script into the editor and press the green "Commit Changes" +5. Click the green "Create pull request" on the following page +6. In your PR description, include any special requirements (unique mounts, GPU usage, special environment variables, etc.) diff --git a/docs/install-scripts/curated/index.md b/docs/features/apps/install-scripts/curated/index.md similarity index 100% rename from docs/install-scripts/curated/index.md rename to docs/features/apps/install-scripts/curated/index.md diff --git a/docs/install-scripts/overview.md b/docs/features/apps/install-scripts/overview.md similarity index 100% rename from docs/install-scripts/overview.md rename to docs/features/apps/install-scripts/overview.md diff --git a/docs/install-scripts/reference/macros.md b/docs/features/apps/install-scripts/reference/macros.md similarity index 100% rename from docs/install-scripts/reference/macros.md rename to docs/features/apps/install-scripts/reference/macros.md diff --git a/docs/install-scripts/reference/schema.md b/docs/features/apps/install-scripts/reference/schema.md similarity index 100% rename from docs/install-scripts/reference/schema.md rename to docs/features/apps/install-scripts/reference/schema.md diff --git a/docs/features/folders/index.md b/docs/features/folders/index.md new file mode 100644 index 00000000..b7121d75 --- /dev/null +++ b/docs/features/folders/index.md @@ -0,0 +1,47 @@ +# Folders + +As with most computer systems, folders are used to store data. Some are automatically created when applications are installed, but users can create folders themselves for sharing files over a network or backing up other devices (Apple Time Machine, Windows Backup, etc). + +## Creating Folders + +When creating a folder, you have several options to configure: + +**Location**: Choose which storage pool the folder will be created on. This is especially useful if you have multiple pools with different performance characteristics or purposes. + +**Access**: Choose who has access to this folder and what permissions they have. We'll cover this in more detail in the Users and Permissions section below. + +**Quota**: Set storage limits for individual folders to control how much space they can use. This helps manage disk usage when multiple people or applications share your server. + +**Time Machine**: Enable Time Machine support to let your Macs back up directly to this folder. This sets up the folder with the proper configuration for Apple's backup system. + +**Encryption**: You can optionally enable encryption on folders you create. Encrypted folders can be "locked" or "unlocked" using a custom passphrase created by the administrator specifically for making the folder accessible. Note that encryption can only be enabled during folder creation and cannot be disabled once the folder is created. + +## How to Access Files and Folders Over the Network + +Each folder has a "Browse" button that shows you exactly how to connect from your device. If you created a private server you will need to connect to that folder using the associated Users credentials. + +**On Mac**: Open Finder, click "Go" in the menu bar, select "Connect to Server". Paste the SMB link into the "Server Address" field and click "Connect". + +**On Windows**: Open File Explorer, right-click on "This PC", then "Map network drive". Paste the SMB link below into the "Folder" field and click "Finish" to connect. + +## Users and Permissions + +Your account is automatically an administrator, which means you always have full access to all your folders. Creating additional users is optional and comes in handy when you want other people to access specific folders without sharing your admin credentials. + +**Public folders**: Anyone can access these folders. +**Private folders**: Only you and specifically selected users can access these folders. + +You can also give users specific types of access to folders. + +**Read access**: Users can view and download files but can't change anything. +**Write access**: Users can add, modify, and delete files in the folder. + +User accounts you create here are just for folder access through network file browsers like Finder or Windows Explorer. They don't give people any control over your server or applications. + +## System Folders + +When you install apps they automatically create "System Folders" for their data. These appear separately from your personal folders and are managed by the apps themselves. + +**What you should know:** +- **Reserved names**: Certain folder names like "Downloads" are reserved for system use. If you create a folder with a reserved name, it will automatically appear in System Folders instead of your personal folders +- **Default locations**: These folders have default locations, but you can change where they're created in [locations](/features/settings/#locations) diff --git a/docs/features/index.md b/docs/features/index.md new file mode 100644 index 00000000..4b3313fa --- /dev/null +++ b/docs/features/index.md @@ -0,0 +1,24 @@ +# Features + +Now that your server is up and running, you'll have access +to everything you need to manage your data, run applications, +share files across your network, and keep your system +running smoothly. + +## Dashboard + +Right after completing the setup wizard, you will be taken to the HexOS Dashboard. From here, you can review system activities, apply OS updates, monitor resource usage, and control your installed applications/virtual machines. + +By default you will see system information, storage, and apps on your dashboard. However this display is configurable in [settings preferences](/features/settings/#preferences). + +## Notifications + +HexOS provides notifications to users in two primary ways: +- All notifications are delivered to the HexOS “Bell” icon, visible on all pages. +- Critical notifications (e.g. disk failures) are also delivered automatically to you via email. + +Notifications can be both marked as read and dismissed, and previous notifications can be viewed from within the messaging archive. + +## Profile + +Your profile menu lives in the top-right corner of every page. From there you can switch to dark mode, change languages, jump to our Community Hub, send us feedback or sign out. diff --git a/docs/features/notifications/index.md b/docs/features/notifications/index.md new file mode 100644 index 00000000..8fb967d9 --- /dev/null +++ b/docs/features/notifications/index.md @@ -0,0 +1,29 @@ +# Notifications + +HexOS provides notifications to users in two primary ways: + +- All notifications are delivered to the HexOS "Bell" icon, visible on all pages. +- Critical notifications (e.g. disk failures) are also delivered automatically to you via email. + +Notifications can be both marked as read and dismissed, and previous notifications can be viewed from within the messaging archive. + +## SMART Errors + +Your drives collect health data that HexOS monitors for potential problems. When you see SMART errors, it means the system has detected something that warrants investigation. This could indicate a drive issue that needs attention, but doesn't necessarily mean immediate replacement is required. + +Learn more about [SMART](https://kb.synology.com/en-global/DSM/tutorial/What_is_SMART) technology. + +## System Health Notifications + +HexOS monitors your server's hardware and storage systems. You'll get alerts for things like overheating, storage pool problems, or missing drives that need your attention. + +## Task Notifications + +When you start operations that take time to complete, such as +installing apps, managing storage, or system updates, HexOS +shows you a task so you know something is happening in the +background. + +## Managing Notifications + +You have control over how notifications appear and persist in your system. You can mark notifications as read by clicking on them, dismiss them when you've handled them, or use "Mark All as Read" and "Dismiss All" to handle multiple notifications at once. You can also view older notifications in the archive, with all notification history accessible through the [activity messages](/features/settings/#activity-history) page. diff --git a/docs/features/overview.md b/docs/features/overview.md deleted file mode 100644 index 82d82363..00000000 --- a/docs/features/overview.md +++ /dev/null @@ -1,21 +0,0 @@ -# Features - -some text that gives an introduction to what all the features encompass. - -## Dashboard - -Immediately after completing the setup wizard, you will be first taken to the HexOS Dashboard. From here, you can review system activities, apply OS updates, monitor resource usage, and control your installed applications/virtual machines. - -By default you will see information on your system, (activity messages, hardware information) storage, and apps. However this display is configurable in [setttings]. - -## Notifications - -HexOS provides notifications to users in two primary ways: -- All notifications are delivered to the HexOS “Bell” icon, visible on all pages. -- Critical notifications (e.g. disk failures) are also delivered automatically to you via email. - -Notifications can be both marked as read and dismissed, and previous notifications can be viewed from within the messaging archive. - -## Profile - -Your user profile is also available on all pages of HexOS, where you can toggle dark mode, launch the Community Hub, give feedback to us, or logout. diff --git a/docs/features/settings/experimental-features/index.md b/docs/features/settings/experimental-features/index.md new file mode 100644 index 00000000..d8ca5b9e --- /dev/null +++ b/docs/features/settings/experimental-features/index.md @@ -0,0 +1,11 @@ +# Experimental Features + +Advanced functionality that's still being refined. These features are stable enough to use but aren't quite ready for everyday users. They may have rough edges, or require more technical knowledge to use effectively. + +Enable experimental features in your preferences when you want access to advanced functionality. + +## Current Features + +- **Custom Install Scripts** - View and edit the install scripts that power app installations. Customize configurations or create scripts for non-curated apps. + +- **Advanced Encryption Options** - Access additional encryption settings when creating folders, beyond the standard encryption toggle. \ No newline at end of file diff --git a/docs/features/settings/index.md b/docs/features/settings/index.md new file mode 100644 index 00000000..18defb24 --- /dev/null +++ b/docs/features/settings/index.md @@ -0,0 +1,23 @@ +# Settings + +Need to tweak how your server behaves? This is where you'll find all the configuration options, from network setup to customizing your dashboard to choosing where different types of files get stored. + +## Network + +Configure your server's network connection and how devices reach it. Set up network interfaces with static IPs if needed, change your server's hostname, and handle advanced networking like VLANs for complex setups. + +## Preferences + +Fine tune your HexOS experience with dashboard controls. +Toggle entire dashboard sections (storage, apps, system) or drill down to individual items - hide specific storage pools, system health metrics, processor info, memory usage, or individual network interfaces. Change your language, switch to dark mode, and enable [experimental features](/features/settings/experimental-features/). + +## Locations + +A comprehensive location editor where you can customize paths for applications and folders. Set where applications install, choose storage locations for downloads, documents, media files, virtual machines, and more across your different storage pools. + +## Reset Options + +Sometimes you need a fresh start, or want to hand your server off to someon eelse. Currently you have two options. + +- **Unclaim Server** will remove your server from our database. Nothing happens to the physical server. You will no longer be able to access it through HexOS, but it can be reclaimed. +- **Wipe everything** will delete all data on all drives and reset your server to defaults. \ No newline at end of file diff --git a/docs/features/storage/storage.md b/docs/features/storage/storage.md new file mode 100644 index 00000000..577c13b0 --- /dev/null +++ b/docs/features/storage/storage.md @@ -0,0 +1,40 @@ +# Storage + +This is where you'll find all your pools and drives, and handle anything related to storage. Whether it's creating new pools, adding more space, swapping drives, or fixing any issues that pop up. + +## Creating Storage Pools + +When you first set up your server, you likely created at least one storage pool. If you have unused drives, you can create a new pool by selecting which drives to group together. + +It's worth mentioning the number of drives you choose matters. Too few drives and you won't have proper redundancy, or the ability to add more storage later on. + +## Growing Your Storage + +As your server usage grows, you might need more storage capacity or need to +handle drive issues. HexOS gives you options to expand and maintain your +storage. + +**Extending drives**: Add more drives to your existing pool for more space. + +**Expanding drives**: Upgrade individual drives one at a time. + +## Replacing Drives + +Drives fail. It's not a matter of if, but when. The storage interface will show you when there are problems relating to your pools and drives. + +When drives start having [SMART](https://kb.synology.com/en-global/DSM/tutorial/What_is_SMART) errors, I/O problems, or go missing entirely, you'll see visual indicators right in the interface. When a drive needs replacement, HexOS will look at your available unused drives and suggest suitable replacements. + +If you don't have a replacement drive on hand, check out our guide on [selecting drives](https://hexos.com/selecting-drives). + +## Critical Errors + +Sometimes storage issues are more serious than a single drive failure. Before assuming the world is falling apart, try restarting your server and seeing if some of the errors go away. +If the errors persist, here's a quick overview of what you may see. + +**Pool degradation**: Your pool is running but weakened. Check that all drives are properly connected and look for drive errors. Usually this means a drive needs replacement, but your data is still safe. + +**Pool offline**: Your pool isn't accessible right now. This often happens when too many drives fail at once or there's a connection issue. Check drive connections first, then look for multiple drive failures. + +**Multiple drive problems**: If you lose more drives than your redundancy can handle, you're in data loss territory. Stop using the system immediately and consider professional data recovery if the data is critical. + +The key is acting quickly when you see alerts. Most pool problems start small and get worse if ignored. \ No newline at end of file diff --git a/docs/install-scripts/contributing.md b/docs/install-scripts/contributing.md deleted file mode 100644 index e54d4265..00000000 --- a/docs/install-scripts/contributing.md +++ /dev/null @@ -1,9 +0,0 @@ -# Contributing a new app - -If you would like to contribute your curation to the official HexOS app curations you can follow this guide, or just share your install script in our forums: -1. Test your custom curation in HexOS and verify it works -2. Click [Here](https://github.com/eshtek/hexos-docs/new/main/docs/public/install-scripts) -3. Click the green "Fork this repository" -4. Paste the contents of your install script into the editor and press the green "Commit Changes" -5. Click the green "Create pull request" on the following page -6. In your PR description, include any callouts (unique mounts, GPU usage, special env, etc.) diff --git a/docs/licensing/index.md b/docs/licensing/index.md new file mode 100644 index 00000000..468f58c6 --- /dev/null +++ b/docs/licensing/index.md @@ -0,0 +1,9 @@ +# Licensing & Usage Rights + +## Lifetime License Includes Right to Transfer to New Hardware + +## One Active Server Per License at a Time + +## Unclaimed Servers Can Still Be Managed via TrueNAS SCALE UI + +## Features Not Included in Lifetime (Metered Services, Support, etc.) \ No newline at end of file diff --git a/docs/troubleshooting/index.md b/docs/troubleshooting/index.md new file mode 100644 index 00000000..3657dbee --- /dev/null +++ b/docs/troubleshooting/index.md @@ -0,0 +1,71 @@ +# Troubleshooting + +## Cannot Image USB Stick with ISO + +If you're having trouble creating a bootable USB drive from the HexOS ISO, try these steps: + +**Use a different imaging tool**: If Rufus isn't working, try balenaEtcher or the official tool recommended for your operating system. + +**Try a different USB drive**: Some older or damaged USB drives can cause imaging problems. + +**Download the ISO again**: Sometimes download corruption can cause imaging issues. + +## Failures During the Installation Process + +Installation problems can happen for various reasons: + +**Hardware compatibility**: Check that your hardware meets the minimum requirements and is supported. + +**Corrupted installation media**: Re-create your USB installation drive with a fresh ISO download. + +**Memory issues**: Run a memory test if the installer crashes or behaves erratically. + +## Server Fails to Get an IP Address on First Boot After Install + +Network connectivity problems after installation: + +**Check network cable**: Ensure your ethernet cable is properly connected and working. + +**Router/switch issues**: Try connecting to a different network port or restarting your network equipment. + +**Network configuration**: Some networks require manual IP configuration rather than DHCP. + +## Problems Claiming Your Server + +If you can't claim your server on deck.hexos.com: + +**Network connectivity**: Ensure your server can reach the internet and deck.hexos.com is accessible. + +**Account issues**: Verify you're logged into the correct HexOS account. + +**Server already claimed**: Check if the server might already be claimed by another account. + +## Can't Login to deck.hexos.com + +Authentication problems with the HexOS management portal: + +**Password reset**: Use the forgot password feature if you can't remember your credentials. + +**Account verification**: Check if your account email needs to be verified. + +**Browser issues**: Try a different browser or clear your browser cache and cookies. + +## Server Not Discovered + +If deck.hexos.com can't find your server: + +**Network discovery**: Ensure your server and the device you're browsing from are on the same network. + +**Firewall settings**: Check that your network firewall isn't blocking discovery. + +**Server status**: Verify the server has finished booting and is running properly. + +## Password Incorrect + +When you can't authenticate to your server: + +**Default credentials**: Check if you're using the correct default username and password from the installation. + +**Caps lock**: Verify caps lock isn't affecting your password entry. + +**Keyboard layout**: Ensure your keyboard layout matches what you used during setup. \ No newline at end of file From 935e54b451ade13df1be2518d1c24919b369cbac Mon Sep 17 00:00:00 2001 From: Cole Manel Date: Wed, 24 Sep 2025 11:56:03 -0400 Subject: [PATCH 4/4] format install guide --- .../installation/InstallGuide.md | 176 ++++++++++-------- docs/getting-started/setup/CompleteSetup.md | 5 +- 2 files changed, 104 insertions(+), 77 deletions(-) diff --git a/docs/getting-started/installation/InstallGuide.md b/docs/getting-started/installation/InstallGuide.md index 14682ac9..a5dad717 100644 --- a/docs/getting-started/installation/InstallGuide.md +++ b/docs/getting-started/installation/InstallGuide.md @@ -1,79 +1,105 @@ # Illustrated Installation Guide +## Download the HexOS Installer -**Install Guide:** - -- Start by downloading the installer iso from either link: - - [https://downloads.hexos.com/TrueNAS-SCALE-24.10.2.2-HexOS.iso](https://downloads.hexos.com/TrueNAS-SCALE-24.10.2.2-HexOS.iso)  - - [https://hexos-downloads.sfo3.cdn.digitaloceanspaces.com/TrueNAS-SCALE-24.10.2.2-HexOS.iso](https://hexos-downloads.sfo3.cdn.digitaloceanspaces.com/TrueNAS-SCALE-24.10.2.2-HexOS.iso "https://hexos-downloads.sfo3.cdn.digitaloceanspaces.com/TrueNAS-SCALE-24.10.2.2-HexOS.iso")  - - SHA256 Checksum:   - - 0d3ee32e5ecf011da78ddcb49d0866478fb6a1ddfeddd563f458a23641c8d1c5 - - _(current as of 6/26/25)_ -   -- To flash to a USB you will need a copy of Balena Etcher. - - Download link: [https://etcher.balena.io/#download-etcher](https://etcher.balena.io/#download-etcher) - - Install, then open Etcher - - Select "Flash from File" and find your downloaded iso. - - Select the target USB drive you want to use for your install media - - Click 'Flash!' - - \* NOTE: Using Rufus to flash the installer is NOT recommended, and has been causing issues for many users. -   -- Once completed, insert the USB into the machine you will be installing HexOS on, and power on the machine. -   -- The first screen that requests input is this. - - Select "Start HexOS Installation" (default) - - _(This screen will pass automatically after a moment)_ - - [![Capture.PNG.68aa841b48189723e75377b4eae0e4f5.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture.PNG.68aa841b48189723e75377b4eae0e4f5.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture.PNG.68aa841b48189723e75377b4eae0e4f5.PNG "Enlarge image") - -- Next, you will see the console do console things for a bit, then it will ask what you want to do. - - We want option 1. "Install/Upgrade" - - [![Capture2.PNG.0632104eaf1d3158bd759f4a8b595244.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture2.PNG.0632104eaf1d3158bd759f4a8b595244.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture2.PNG.0632104eaf1d3158bd759f4a8b595244.PNG "Enlarge image") - -- Next up, Where do you want to install the OS? - - **Use the arrow keys to navigate to the correct drive, press the space bar to select it.** - - _"**\[\*\]**" Indicates that the device has been selected._ - - [![Capture3.PNG.8efa34d929a7a8dd6e148ebc17172509.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture3.PNG.8efa34d929a7a8dd6e148ebc17172509.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture3.PNG.8efa34d929a7a8dd6e148ebc17172509.PNG "Enlarge image") - -- Next, you will confirm that you understand that the drive(s) you selected will be FULLY ERASED. - - [![Capture4.PNG.20de862b21fdbe599a413abfc6bc5db6.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture4.PNG.20de862b21fdbe599a413abfc6bc5db6.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture4.PNG.20de862b21fdbe599a413abfc6bc5db6.PNG "Enlarge image") - -- **OK, This is the weird one!**  - -  We want the first option**; "Administrative user (truenas\_admin)"** - - _[If you selected the 2nd option please see Pduncharme's reply below for a solution!](https://hub.hexos.com/topic/103-illustrated-installation-guide-start-here/#findComment-1958)_ - - _An alternative solution would be to re-start the install. Not ideal, but it also doesn't take all that long._ - - _(this screen will likely be removed in later versions of the installer)_ - - [![Capture5.PNG.f7af55f85dc45fff3932704006737410.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture5.PNG.f7af55f85dc45fff3932704006737410.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture5.PNG.f7af55f85dc45fff3932704006737410.PNG "Enlarge image") - -- Next we need to set the root password for the TrueNAS install that underpins HexOS. - - Be sure not to lose this, you will need it later when adopting your server on Deck.HexOS.com - - **\*NOTE\*: If you use a NON US KEYBOARD please be cautious about special characters, as the installer defaults to a US keyboard layout!** - - _[See this comment for details.](https://hub.hexos.com/topic/103-illustrated-installation-guide-start-here/page/2/#findComment-8073)_ - - [![Capture6.PNG.2757a99cb3d6eff2456fae08f5d8af22.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture6.PNG.2757a99cb3d6eff2456fae08f5d8af22.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture6.PNG.2757a99cb3d6eff2456fae08f5d8af22.PNG "Enlarge image") - -- Next, EFI Boot optons. Generally, "Yes" should be fine for newer hardware. - - [![Capture7.PNG.882149a9a6a418c51547772762cab939.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture7.PNG.882149a9a6a418c51547772762cab939.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture7.PNG.882149a9a6a418c51547772762cab939.PNG "Enlarge image") - -- Next, the installer will do installer things for a few minutes... - - [![Capture8.PNG.415546fcc3c0eddfc6051012a28c8a7e.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture8.PNG.415546fcc3c0eddfc6051012a28c8a7e.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture8.PNG.415546fcc3c0eddfc6051012a28c8a7e.PNG "Enlarge image") - -- Then you should be greeted by this screen. - - You can now remove the install USB and restart your server. - - [![Capture9.PNG.b01ff55fcd882a5612dd01b299807662.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture9.PNG.b01ff55fcd882a5612dd01b299807662.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture9.PNG.b01ff55fcd882a5612dd01b299807662.PNG "Enlarge image") - -- After restarting, you should see a boot select screen again. - - You can ignore this. The default option is the right one, and it will pass after a few seconds - - [![Capture10.PNG.6dd4a02dcdb72261ad0857b5af351bb1.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture10.PNG.6dd4a02dcdb72261ad0857b5af351bb1.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture10.PNG.6dd4a02dcdb72261ad0857b5af351bb1.PNG "Enlarge image") - --  Next, the console will got displaying stuff  along these lines while starting up the server. - - _Tip: If your server fails to start booting TrueNAS/HexOS you may need to get into the bios and check your boot device order._ - - [![Capture11.thumb.PNG.6a43deaa983d715784365f338659d44c.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture11.thumb.PNG.6a43deaa983d715784365f338659d44c.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture11.PNG.8d234b71bdcd3fbbdd5ad5389338e67f.PNG) - -- If you you made it here, CONGRATS! Your install is complete! - - **H****ead to [https://deck.hexos.com/](https://deck.hexos.com/) to configure your server!** - - _(The "Console Setup" screen is the default display when TrueNAS/HexOS is running.)_ - - [![Capture12.thumb.PNG.44c581cd145b735c1ce98f591991f934.PNG](https://hub.hexos.com/uploads/monthly_2024_11/Capture12.thumb.PNG.44c581cd145b735c1ce98f591991f934.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture12.PNG.ad70047f68f85e17303c4c874af95fc1.PNG) - - - - +- Download the installer ISO from either link: + - [https://downloads.hexos.com/TrueNAS-SCALE-24.10.2.2-HexOS.iso](https://downloads.hexos.com/TrueNAS-SCALE-24.10.2.2-HexOS.iso) + - [https://hexos-downloads.sfo3.cdn.digitaloceanspaces.com/TrueNAS-SCALE-24.10.2.2-HexOS.iso](https://hexos-downloads.sfo3.cdn.digitaloceanspaces.com/TrueNAS-SCALE-24.10.2.2-HexOS.iso) + - SHA256 Checksum: `0d3ee32e5ecf011da78ddcb49d0866478fb6a1ddfeddd563f458a23641c8d1c5` +- _(current as of 6/26/25)_ +## Create Installation USB + +- Download Balena Etcher: [https://etcher.balena.io/#download-etcher](https://etcher.balena.io/#download-etcher) + - Install and open Etcher + - Select "Flash from File" and choose your downloaded ISO + - Select your target USB drive + - Click 'Flash!' + +**Important**: Do not use Rufus - it causes issues for many users. Stick with Balena Etcher. + +## Installation Process + +- Insert the USB into your server and power it on + +### Boot Screen + +- Select "Start HexOS Installation" (default) +- This screen will pass automatically after a moment + +[![Boot Screen](https://hub.hexos.com/uploads/monthly_2024_11/Capture.PNG.68aa841b48189723e75377b4eae0e4f5.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture.PNG.68aa841b48189723e75377b4eae0e4f5.PNG "Enlarge image") + +### Installation Menu + +- After the system loads, choose option 1: "Install/Upgrade" + +[![Installation Menu](https://hub.hexos.com/uploads/monthly_2024_11/Capture2.PNG.0632104eaf1d3158bd759f4a8b595244.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture2.PNG.0632104eaf1d3158bd759f4a8b595244.PNG "Enlarge image") + +### Select Installation Drive + +- **Use arrow keys to navigate, spacebar to select your installation drive** +- "**[*]**" indicates the device is selected + +[![Drive Selection](https://hub.hexos.com/uploads/monthly_2024_11/Capture3.PNG.8efa34d929a7a8dd6e148ebc17172509.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture3.PNG.8efa34d929a7a8dd6e148ebc17172509.PNG "Enlarge image") + +### Confirm Drive Erasure + +- Confirm you understand the selected drive(s) will be **FULLY ERASED** + +[![Drive Erasure Warning](https://hub.hexos.com/uploads/monthly_2024_11/Capture4.PNG.20de862b21fdbe599a413abfc6bc5db6.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture4.PNG.20de862b21fdbe599a413abfc6bc5db6.PNG "Enlarge image") + +### User Account Setup + +- **Important**: Choose the first option: "Administrative user (truenas_admin)" +- If you accidentally select the wrong option, [see this solution](https://hub.hexos.com/topic/103-illustrated-installation-guide-start-here/#findComment-1958) or restart the installation + +[![User Account Setup](https://hub.hexos.com/uploads/monthly_2024_11/Capture5.PNG.f7af55f85dc45fff3932704006737410.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture5.PNG.f7af55f85dc45fff3932704006737410.PNG "Enlarge image") + +### Set Root Password + +- Set the root password - **save this password, you'll need it later** +- **Non-US keyboard users**: Be careful with special characters as the installer uses US keyboard layout. [See details here](https://hub.hexos.com/topic/103-illustrated-installation-guide-start-here/page/2/#findComment-8073) + +[![Root Password Setup](https://hub.hexos.com/uploads/monthly_2024_11/Capture6.PNG.2757a99cb3d6eff2456fae08f5d8af22.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture6.PNG.2757a99cb3d6eff2456fae08f5d8af22.PNG "Enlarge image") + +### EFI Boot Options + +- Choose "Yes" for newer hardware (generally recommended) + +[![EFI Boot Options](https://hub.hexos.com/uploads/monthly_2024_11/Capture7.PNG.882149a9a6a418c51547772762cab939.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture7.PNG.882149a9a6a418c51547772762cab939.PNG "Enlarge image") + +### Installation Progress + +- The installer will run for a few minutes... + +[![Installation Progress](https://hub.hexos.com/uploads/monthly_2024_11/Capture8.PNG.415546fcc3c0eddfc6051012a28c8a7e.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture8.PNG.415546fcc3c0eddfc6051012a28c8a7e.PNG "Enlarge image") + +### Installation Complete + +- Remove the install USB and restart your server + +[![Installation Complete](https://hub.hexos.com/uploads/monthly_2024_11/Capture9.PNG.b01ff55fcd882a5612dd01b299807662.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture9.PNG.b01ff55fcd882a5612dd01b299807662.PNG "Enlarge image") + +## First Boot + +### Boot Screen + +- The boot select screen will appear again - ignore it +- The default option is correct and will auto-select + +[![First Boot Screen](https://hub.hexos.com/uploads/monthly_2024_11/Capture10.PNG.6dd4a02dcdb72261ad0857b5af351bb1.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture10.PNG.6dd4a02dcdb72261ad0857b5af351bb1.PNG "Enlarge image") + +### System Startup + +- The console will display startup information +- **Tip**: If boot fails, check your BIOS boot device order + +[![System Startup](https://hub.hexos.com/uploads/monthly_2024_11/Capture11.thumb.PNG.6a43deaa983d715784365f338659d44c.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture11.PNG.8d234b71bdcd3fbbdd5ad5389338e67f.PNG) + +### Success! + +- **Installation complete!** +- **Next step**: Head to [https://deck.hexos.com/](https://deck.hexos.com/) to configure your server +- The "Console Setup" screen shows when HexOS is running properly + +[![Console Setup Screen](https://hub.hexos.com/uploads/monthly_2024_11/Capture12.thumb.PNG.44c581cd145b735c1ce98f591991f934.PNG)](https://hub.hexos.com/uploads/monthly_2024_11/Capture12.PNG.ad70047f68f85e17303c4c874af95fc1.PNG) \ No newline at end of file diff --git a/docs/getting-started/setup/CompleteSetup.md b/docs/getting-started/setup/CompleteSetup.md index fab0f5df..4c615b50 100644 --- a/docs/getting-started/setup/CompleteSetup.md +++ b/docs/getting-started/setup/CompleteSetup.md @@ -50,6 +50,7 @@ Finally, give your server a name and your server is good to go! ### What's Next? -Your server will finish initializing momentarily and bring you to the dashboard. -From here you can explore all of HexOS's features, check out our [Features Guide] to learn more! +Your server will finish initializing and bring you to the HexOS [dashboard](/features/). This is your control center where you can monitor your server, manage storage, install apps, and configure settings. + +Ready to explore? Check out our [Features Guide](/features/) to learn about everything HexOS can do!