I want to install Dappnode
-I own a machine where I want to install Dappnode software
+Install on Linux (Debian/Ubuntu) or macOS
I have bought a Dappnode or I already installed it
- +
I own a machine where I want to install Dappnode software
+Install on Linux (Debian/Ubuntu) or macOS
diff --git a/docs/user/install/linux.md b/docs/user/install/linux.md new file mode 100644 index 000000000..7683da7d6 --- /dev/null +++ b/docs/user/install/linux.md @@ -0,0 +1,71 @@ +--- +title: "Linux (Debian/Ubuntu)" +llm_description: "Overview of installing Dappnode on Linux: ISO and script methods for server and desktop use cases." +--- + +# Linux (Debian/Ubuntu) + +Dappnode runs natively on Debian-based Linux distributions. You can install it on a dedicated server for 24/7 operation or on your personal Linux desktop or laptop. + +## Installation Methods + +### 1. [ISO Installation](/docs/user/install/iso) + +The ISO method performs a clean install: it wipes the disk and installs Dappnode over Debian. This is the recommended approach for dedicated machines. + +- **Best for**: New dedicated servers, users who want a turnkey setup. +- **Supported architectures**: amd64 + +### 2. [Script Installation](/docs/user/install/script) + +The script method installs Dappnode on top of an existing Debian or Ubuntu system. It offers more flexibility through flags that control which components are installed. + +- **Best for**: Existing Debian/Ubuntu systems, cloud servers, ARM devices, or users who want more control over the installation. + +## Server vs Desktop Installation + +The installer supports different modes depending on whether your machine will be a dedicated server or a personal desktop: + +### Server (24/7, dedicated machine) + +Install the full Dappnode package set. This is the default behavior: + +```bash +sudo wget -O - https://installer.dappnode.io | sudo bash +``` + +This installs all core components including HTTPS, BIND, IPFS, VPN, WIREGUARD, DAPPMANAGER, WIFI, NOTIFICATIONS, and PREMIUM. + +**Connectivity options after installation:** + +- **WiFi**: Scan for `DAppNodeWIFI` and connect. Get credentials with `dappnode_wifi`. +- **Wireguard VPN** (recommended): Import credentials from `dappnode_wireguard`. +- **OpenVPN**: Import credentials from `dappnode_openvpn`. +- **Local Proxy**: Connect to the same router and go to `http://dappnode.local`. + +### Desktop / Personal Computer (lite mode) + +If you want to run Dappnode on your personal Linux desktop or laptop, use the `--lite` flag. This installs a reduced set of components (BIND, VPN, WIREGUARD, DAPPMANAGER, NOTIFICATIONS, PREMIUM) without WIFI, IPFS, or HTTPS: + +```bash +sudo wget -O - https://installer.dappnode.io | sudo bash -s -- --lite +``` + +**Connectivity options after installation:** + +- **Wireguard VPN** (recommended): Import credentials from `dappnode_wireguard`. +- **OpenVPN**: Import credentials from `dappnode_openvpn`. + +:::caution .dappnode domains on Desktop mode +When running in `--lite` (desktop) mode, `.dappnode` domain resolution is currently under investigation and may not work as expected. This is a known limitation that is expected to be fixed in a future release. +::: + +Once connected via VPN, access the Dappnode UI at [http://my.dappnode](http://my.dappnode). + +## Next Steps + +- [ISO Installation guide](/docs/user/install/iso) — step-by-step clean install +- [Script Installation guide](/docs/user/install/script) — install on an existing system +- [Advanced Script Options](/docs/user/install/script/advanced) — all flags and environment variables +- [ARM Installation](/docs/user/install/arm) — ARM-specific instructions +- [Dappnode Commands](/docs/user/install/dappnode-commands) — CLI reference diff --git a/docs/user/install/macos.md b/docs/user/install/macos.md new file mode 100644 index 000000000..6eab8cb52 --- /dev/null +++ b/docs/user/install/macos.md @@ -0,0 +1,96 @@ +--- +title: "macOS Installation" +llm_description: "Guide to install Dappnode on macOS via script, covering both desktop and server modes." +--- + +# macOS Installation + +Dappnode can be installed on macOS (Apple Silicon and Intel) using the installation script. The installer automatically detects your Mac model and adjusts the installation accordingly: + +- **Server-class Macs** (Mac mini, Mac Studio, Mac Pro): Full installation with all services, suitable for 24/7 operation. +- **Desktop/Laptop Macs** (MacBook, iMac): Minimal installation optimized for personal use alongside your day-to-day work. + +## Prerequisites + +Before installing Dappnode, you need: + +- [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/) installed and running +- `curl` or `wget` (macOS includes `curl` by default) + +:::info Docker Desktop +Make sure Docker Desktop is running before starting the installation. You can verify it by running `docker ps` in your terminal. +::: + +## Installation + +### Desktop / Personal Mac (MacBook, iMac) + +If you are running Dappnode on a Mac that you also use as your personal computer, use the `--minimal` flag. This installs only the essential Dappnode components (BIND, DAPPMANAGER, NOTIFICATIONS, PREMIUM), keeping your system lightweight: + +```bash +sudo wget -O - https://installer.dappnode.io | sudo bash -s -- --minimal +``` + +### Server Mac (Mac mini, Mac Studio, Mac Pro) + +For always-on Macs intended to run as dedicated servers, use the full installation: + +```bash +sudo wget -O - https://installer.dappnode.io | sudo bash +``` + +The installer automatically detects server-class Mac models and installs the full package set including WIFI, IPFS, VPN, WIREGUARD, and HTTPS. + +:::tip +If you have a Mac mini that you use as a personal desktop rather than a server, you can force the minimal installation by passing `--minimal`. +::: + +## Connecting to Dappnode + +After installation, the script will display your VPN credentials. How you connect depends on your installation type: + +### Desktop / Personal Mac + +Since Dappnode is running locally on the same machine, connect using: + +- **Wireguard VPN** (recommended): Import the Wireguard credentials displayed after installation into the [Wireguard app](https://apps.apple.com/app/wireguard/id1451685025). Use `dappnode_wireguard --localhost` to get credentials optimized for local connections. +- **OpenVPN**: Import the OpenVPN credentials into your preferred OpenVPN client. Use `dappnode_openvpn` to retrieve them. + +Once connected via VPN, access the Dappnode UI at [http://my.dappnode](http://my.dappnode). + +### Server Mac + +For a server Mac on your local network, you have additional connectivity options: + +- **WiFi**: Scan for `DAppNodeWIFI` and connect. Get WiFi credentials with `dappnode_wifi`. +- **Wireguard VPN** (recommended): Import credentials from `dappnode_wireguard` into the Wireguard app. +- **OpenVPN**: Import credentials from `dappnode_openvpn` into your OpenVPN client. + +Once connected, access the Dappnode UI at [http://my.dappnode](http://my.dappnode). + +## macOS-Specific Notes + +- **Docker Desktop**: Dappnode runs inside Docker Desktop on macOS. Make sure Docker Desktop is configured to start at login if you want Dappnode to be available after a reboot. +- **File paths**: On macOS, Dappnode files are stored under `~/dappnode/` instead of `/usr/src/dappnode/`. +- **Host scripts**: Some Linux-specific host operations are automatically disabled on macOS (`DISABLE_HOST_SCRIPTS=true`). +- **Sleep/Suspend**: If your Mac goes to sleep, Docker containers will be paused. Disable sleep in System Settings for server usage. + +## Restore to the Latest Version + +To update Dappnode to the latest version without erasing any data: + +```bash +sudo wget -O - https://installer.dappnode.io | sudo UPDATE=true bash +``` + +## Uninstall + +To uninstall Dappnode components: + +```bash +wget -qO - https://uninstaller.dappnode.io | sudo bash +``` + +:::info +For advanced installation options (custom packages, IPFS endpoints, etc.), see the [Advanced Script Options](/docs/user/install/script/advanced) page. +::: diff --git a/docs/user/install/overview.md b/docs/user/install/overview.md index 4113701b6..b653fa5fc 100644 --- a/docs/user/install/overview.md +++ b/docs/user/install/overview.md @@ -1,49 +1,87 @@ --- title: "Installation Overview" -llm_description: "Installation overview: minimum hardware specs and comparison of ISO vs script methods." +llm_description: "Installation overview: supported platforms, hardware specs by use case, and installation method comparison." --- # Installation Overview -## Specifications & Minimum Requirements -Dappnode is a Debian-based OS, which makes it friendly with most available commercial hardware. Depending on what you intend to run in your Dappnode you might need higher specifications, but a great number of available features can be used with the following recommendations: -- Intel Core i5/i7 -- 32 GB RAM -- 4 TB NVMe storage +Dappnode can be installed on **Linux (Debian/Ubuntu)** and **macOS** machines. Whether you are setting up a dedicated home server or running Dappnode on your personal computer, choose the platform and installation method that best fits your needs. -As minimum requirements we recommend: -- Intel Core i3 -- 16 GB RAM -- 2 TB NVMe or fast SSD storage +## Supported Platforms -If you don't have enough technical experience to customize your own hardware, remember you can always get a plug n play [Dappnode Home](https://dappnode.com/collections/all) in our online shop. +| Platform | Installation Methods | Notes | +| --- | --- | --- | +| **Linux (Debian/Ubuntu)** | [ISO](/docs/user/install/iso), [Script](/docs/user/install/script) | Recommended for dedicated servers and staking | +| **macOS** | [Script](/docs/user/install/macos) | Apple Silicon & Intel supported | +| **ARM (Linux)** | [Script](/docs/user/install/arm) | Raspberry Pi and similar boards | -## Installation Methods +## Hardware Recommendations -Installing Dappnode can be achieved through two primary methods: +Hardware requirements depend heavily on your intended use case. Below are general guidelines: -### 1. [ISO Installation](/docs/user/install/iso) -- **Description**: This method involves downloading the Dappnode ISO file and using it to directly install Dappnode on your system. -- **Best for**: Most users as it provides a comprehensive setup designed specifically for Dappnode. +### Home Server (24/7 staking, full nodes) -### 2. [Script Installation](/docs/user/install/script) over Debian-based Distribution -- **Description**: If you're already running a Debian-based distribution, you can utilize the Dappnode script to facilitate the installation process. -- **Best for**: Users who want to install Dappnode on a cloud server, ARM device (where it's the only option), or those who desire a specific Debian-based distro. +This is the recommended setup for staking, running full blockchain nodes, and other always-on workloads. -:::note -For ARM-based systems, only the script installation method is available. +| Component | Recommended | Minimum | +| --- | --- | --- | +| CPU | Intel Core i5/i7 or AMD equivalent | Intel Core i3 | +| RAM | 32 GB | 16 GB | +| Storage | 4 TB NVMe | 2 TB NVMe or fast SSD | + +### Personal Desktop / Laptop (light usage) + +If you are running Dappnode on your personal computer for lighter workloads (e.g. testing, light node operation, development), lower specs are acceptable: + +| Component | Recommended | Minimum | +| --- | --- | --- | +| CPU | Intel Core i5 / Apple M1 or better | Intel Core i3 / Apple M1 | +| RAM | 16 GB | 8 GB | +| Storage | 1 TB NVMe or SSD | 512 GB SSD | + +### AI & Advanced Workloads + +Running AI packages or other compute-heavy workloads alongside blockchain nodes requires significantly more resources: + +| Component | Recommended | +| --- | --- | +| CPU | Intel Core i7/i9 or Apple M2 Pro/Max or better | +| RAM | 64 GB+ | +| Storage | 4 TB+ NVMe | +| GPU | Dedicated GPU recommended for AI inference | + +### macOS Compatibility + +Dappnode supports macOS on both Apple Silicon (M1/M2/M3/M4) and Intel Macs. Server-class Macs (Mac mini, Mac Studio, Mac Pro) are recommended for always-on usage. Laptops and iMacs can run Dappnode in desktop/personal mode. See the [macOS installation guide](/docs/user/install/macos) for details. + +:::tip +If you don't have enough technical experience to customize your own hardware, you can always get a plug-and-play [Dappnode Home](https://dappnode.com/collections/all) from our online shop. ::: -Choose the method that best fits your needs and system setup. Make sure to follow the respective installation instructions carefully for a smooth and successful Dappnode deployment. +## Installation Methods at a Glance -:::caution Continuous Uptime +### Linux (Debian/Ubuntu) + +| Method | Best For | Link | +| --- | --- | --- | +| **ISO** | Clean installs on dedicated machines; wipes disk and installs Dappnode over Debian | [ISO Installation](/docs/user/install/iso) | +| **Script (server)** | Installing on an existing Debian/Ubuntu system as a 24/7 server | [Script Installation](/docs/user/install/script) | +| **Script (desktop / `--lite`)** | Installing on a personal Linux desktop or laptop | [Script Installation](/docs/user/install/script) | -Dappnode is designed to run 24/7. Many features and functions within Dappnode, especially blockchain nodes, rely on continuous uptime to maintain their state, sync, and functionality. For instance: +### macOS + +| Method | Best For | Link | +| --- | --- | --- | +| **Script (server)** | Always-on Mac mini / Mac Studio / Mac Pro | [macOS Installation](/docs/user/install/macos) | +| **Script (desktop / `--minimal`)** | Personal MacBook, iMac, or Mac mini used as a desktop | [macOS Installation](/docs/user/install/macos) | + +:::caution Continuous Uptime -- **Blockchain Nodes**: If you have a synced blockchain node and you turn off Dappnode, the node will lose its sync. This means when you turn it back on, it'll take time to catch up to the latest state, which can be resource-intensive and time-consuming. +Dappnode is designed to run 24/7 when used as a server. Many features, especially blockchain nodes and validators, rely on continuous uptime: -- **Validator Nodes**: For users staking on certain blockchain networks, continuous uptime is crucial. Being offline might result in missed opportunities or even penalties. +- **Blockchain Nodes**: Turning off Dappnode causes nodes to lose sync. Re-syncing can be resource-intensive and time-consuming. +- **Validator Nodes**: For staking, continuous uptime is crucial. Being offline may result in missed rewards or penalties. -Considering these aspects, it's recommended to ensure your Dappnode device remains powered on and running at all times. +If you are running Dappnode on a personal desktop or laptop, be aware that shutting down or suspending the machine will stop all Dappnode services. ::: diff --git a/docs/user/install/script.md b/docs/user/install/script.md index f4c4e5f7a..03616fe2d 100644 --- a/docs/user/install/script.md +++ b/docs/user/install/script.md @@ -1,43 +1,73 @@ --- -title: "Script installation" -llm_description: "Install Dappnode via bash script on Debian/Ubuntu, including prerequisites and update commands." +title: "Script Installation" +llm_description: "Install Dappnode via bash script on Debian/Ubuntu, including prerequisites, install modes, and update commands." --- -# Script installation +# Script Installation -You can install Dappnode using the installation script. In this case, we recommend you use Ubuntu or Debian as your operating system. +You can install Dappnode using the installation script on any Debian-based Linux distribution (Debian, Ubuntu). The script method is also the only option for [ARM devices](/docs/user/install/arm) and [macOS](/docs/user/install/macos). ## Prerequisites -Before installing Dappnode, you need to install some prerequisites: +Before installing Dappnode, you need: - [Docker](https://docs.docker.com/install/) -- [Docker-compose](https://docs.docker.com/compose/install/) -- [xz](https://packages.debian.org/sid/xz-utils) +- [Docker Compose](https://docs.docker.com/compose/install/) (plugin or standalone) +- [xz-utils](https://packages.debian.org/sid/xz-utils) -To install all the above prerequisites, execute the command below in the terminal of the machine you want to install Dappnode. If you already have the dependencies installed or you want to install them on your own you can skip this step. +To install all prerequisites at once, run: ```bash sudo wget -O - https://prerequisites.dappnode.io | sudo bash ``` +If you already have the dependencies installed you can skip this step. + ## Install Dappnode -To install Dappnode, execute the next script: +### Server (default — full installation) + +For a dedicated server running 24/7: ```bash sudo wget -O - https://installer.dappnode.io | sudo bash ``` +This installs all core components: HTTPS, BIND, IPFS, VPN, WIREGUARD, DAPPMANAGER, WIFI, NOTIFICATIONS, and PREMIUM. + +### Desktop / Laptop (lite installation) + +For a personal Linux desktop or laptop, use the `--lite` flag to install a reduced set of components: + +```bash +sudo wget -O - https://installer.dappnode.io | sudo bash -s -- --lite +``` + +This installs: BIND, VPN, WIREGUARD, DAPPMANAGER, NOTIFICATIONS, and PREMIUM. + +:::caution .dappnode domains on Desktop mode +When running in `--lite` (desktop) mode, `.dappnode` domain resolution is currently under investigation and may not work as expected. This is a known limitation that is expected to be fixed in a future release. +::: + +### Minimal installation + +For the smallest possible footprint (useful for testing or custom setups): + +```bash +sudo wget -O - https://installer.dappnode.io | sudo bash -s -- --minimal +``` + +This installs only: BIND, DAPPMANAGER, NOTIFICATIONS, and PREMIUM. + ## Reboot -To finalize the installation once it has finished completing, reboot your machine (you might need to do this twice): +After the installation completes, reboot your machine (you might need to do this twice): ```bash shutdown -r now ``` -## Restore to the latest version +## Restore to the Latest Version If you are experiencing any problem or just want to make sure you are running the latest Dappnode versions, execute this command in the Dappnode terminal. This will update the core packages to the latest versions without erasing any data from your volumes. @@ -47,8 +77,12 @@ sudo wget -O - https://installer.dappnode.io | sudo UPDATE=true bash ## Uninstall -This command will uninstall Dappnode components (but not docker et al.). +This command will uninstall Dappnode components (but not Docker). ```bash wget -qO - https://uninstaller.dappnode.io | sudo bash ``` + +## Advanced Options + +The installer supports additional flags and environment variables for fine-grained control over the installation. See the [Advanced Script Options](/docs/user/install/script/advanced) page for the full reference. diff --git a/docs/user/install/script/advanced.md b/docs/user/install/script/advanced.md new file mode 100644 index 000000000..3b5348eac --- /dev/null +++ b/docs/user/install/script/advanced.md @@ -0,0 +1,128 @@ +--- +title: "Advanced Script Options" +llm_description: "Full reference of all CLI flags and environment variables for the Dappnode install script." +--- + +# Advanced Script Options + +The Dappnode installation script supports a variety of flags and environment variables that give you fine-grained control over the installation process. Each flag has an equivalent environment variable. + +## CLI Flags + +| Flag | Description | Equivalent Env Variable | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------- | +| `--update` | Clean existing downloaded artifacts before installing. Useful to force a fresh re-download of all components. | `UPDATE=true` | +| `--static-ip