# Activity Logs Source: https://docs.arct.cloud/account/activity-logs Account activity history. Go to **Settings** > **Activity Log** to view all account activity. ## Logged Actions | Action | Description | | - | - | | **Sign in** | Account login | | **Server created** | New server deployed | | **Server deleted** | Server removed | | **Server actions** | Start, stop, restart, rebuild | | **Payment added** | New payment method added | | **Invoice paid** | Payment processed | | **SSH key added** | New SSH key added | | **SSH key deleted** | SSH key removed | | **Profile updated** | Profile information changed | | **Password changed** | Password updated | | **Ticket created** | Support ticket created | Each entry shows the action, timestamp, and relevant context. > [!TIP] > > If you see activity you don't recognize, [change your password and enable MFA](/account/security) immediately. # API Tokens Source: https://docs.arct.cloud/account/api-tokens Create, turn off and delete tokens for the Arct Cloud API. An API token lets an app, script or service authenticate with the [Arct Cloud API](/api-reference/introduction). It grants access to your account, so treat it like a password. Go to **Settings** > **API Tokens** in the dashboard to manage your tokens. If **API Tokens** isn't listed under **Settings**, the API isn't turned on for your account yet. Contact [support](/account/support-tickets) to ask for access. > [!NOTE] > > A valid payment is required for API access: a [paid invoice](/billing/invoices) or credit added under **Billing** > **Account credits**. A saved card alone doesn't count. Until your account has one, you can't create tokens, and existing tokens get `403 account_not_eligible` on every request. ## Create a Token **1. Open API Tokens** Go to **Settings** > **API Tokens** and click **Create token**. **2. Name the Token** Enter a name you'll recognize, such as `CI deploys`. Use up to 64 letters, digits, spaces, `-`, `_` and `.`. **3. Choose the Access** * **Read only**: view servers, SSH keys, invoices and the catalog. * **Read & write**: also create, change, power, reinstall, resize and delete servers. Creating and resizing servers charges your default card. Choose **Read only** when a tool only needs to look. **4. Choose When It Expires** Pick **Never**, **30 days**, **90 days** or **1 year** from the **Expires** menu. It starts on **Never**. **5. Copy the Token** Click **Create token**, copy the token, then click **Done**. It starts with `arct_`. > [!WARNING] > > The token is shown only once. Copy it now and keep it in a secret manager. Anyone with the token can use your account through the API. You can have up to 10 tokens, including ones that are turned off or expired. Delete tokens you no longer use to make room. ## Token Created Email Each time a token is created, we email the account owner. The email shows the token's name, access, expiry, when it was created (in UTC) and the IP address it was created from. It never contains the token itself. If you didn't create the token, delete it in **Settings** > **API Tokens** and [change your password](/account/security#password). ## View Your Tokens **Settings** > **API Tokens** lists each token with: * its name, with the first 12 characters of the token under it; * its **Access**: **Read only** or **Read & write**, both in the same gray badge; * an **Enabled** switch; * when it **Expires**; * when it was **Last used** (updated at most once a minute); * when it was **Created**. ## Turn a Token Off or On Use the **Enabled** switch next to a token. A token that is off stops working right away, and turning it back on restores it. This is useful to check that nothing still uses a token before you delete it. ## Rename a Token Click **Rename** next to the token, enter the new name, and click **Save**. ## Delete a Token 1. Click **Delete** next to the token 2. Click **Delete token** in the dialog Scripts using the token stop working right away. A deleted token can't be restored. ## Token Activity Go to **Settings** > **Activity Log** and open the **API** tab. It shows when tokens were created, changed and deleted, and the changes made through the API, with the name of the token that made them. > [!TIP] > > If you see API activity you don't recognize, turn the token off, then [secure your account](/account/security). # Security Source: https://docs.arct.cloud/account/security Account and server security. ## Account Security ### Password Use a strong, unique password (12+ characters, mix of letters, numbers, and symbols). ### Two-Factor Authentication (MFA) 1. Go to **Settings** > **Security** 2. Click **Enable MFA** 3. Set up an authenticator app (Google Authenticator, Authy, etc.) > [!WARNING] > > Save your recovery codes. You'll need them if you lose access to your authenticator app. ## Server Security ### Use SSH Keys SSH keys are more secure than passwords. See [SSH Keys](/compute/virtual-machines/ssh-keys). ### Keep OS Updated ```bash theme={null} sudo apt update && sudo apt upgrade -y ``` ### Firewall Open only the ports your application requires. The example below shows SSH, HTTP, and HTTPS: ```bash theme={null} sudo ufw allow 22/tcp sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable ``` > [!WARNING] > > Always allow SSH (port 22) before enabling the firewall. ### Disable Root Login (Optional) ```bash theme={null} adduser yourusername usermod -aG sudo yourusername mkdir -p /home/yourusername/.ssh cp ~/.ssh/authorized_keys /home/yourusername/.ssh/ chown -R yourusername:yourusername /home/yourusername/.ssh sudo sed -i 's/^PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config sudo systemctl restart ssh ``` > [!WARNING] > > Verify you can log in as the new user before disabling root login. # Support Tickets Source: https://docs.arct.cloud/account/support-tickets Open, follow and close support tickets in the dashboard. Ticket support is available 24/7. [Open a new ticket](https://console.arct.cloud/support/new). Tickets are handled by infrastructure engineers. Click **Support** in the dashboard sidebar to see your tickets. ## Open a Ticket **1. Start a New Ticket** Click **Support** in the sidebar, then **Open New Ticket**, or go straight to [console.arct.cloud/support/new](https://console.arct.cloud/support/new). **2. Describe the Issue** Enter a **Subject** of up to 255 characters and choose a **Department**: **Technical Support**, **Billing Question**, **Sales** or **General Inquiry**. **3. Choose a Server (Optional)** Pick the server the ticket is about from **Related Server**. **4. Write the Message** Explain what happened, what you expected and what you have already tried. Attach screenshots or logs if they help. **5. Submit** Click **Submit Ticket**. The ticket opens with the status **Open**. ## Attachments You can attach files to a new ticket and to each reply. * Up to 10 files per message, 10 MB per file and 25 MB in total. * Images: PNG, JPG, GIF, WebP, HEIC and SVG. * Documents: PDF, TXT, MD, CSV, DOC, DOCX, XLS and XLSX. * Logs and configuration: LOG, JSON, YAML, CONF, CFG, INI, TOML, XML, HTML, HAR and PCAP. * Archives: ZIP, GZ, TGZ, TAR and 7Z. * Video: MP4, MOV and WebM. > [!WARNING] > > Never send passwords, private keys or full card numbers in a ticket. ## Ticket Statuses | Status | Meaning | | - | - | | **Open** | Submitted and waiting for review. | | **In progress** | Support is working on it. | | **Awaiting your reply** | Support needs more information from you. | | **Resolved** | Support marked the issue as solved. | | **Closed** | The ticket is closed. | ## Reply, Close or Reopen * Click a ticket in **Support Tickets** to read the conversation and reply. * Click **Close Ticket** when your issue is solved. * Reply to a closed ticket to reopen it, or open a new one. * Tickets marked **Archived** are read-only. To follow up, open a new ticket and mention the archived ticket number. # Account Credit Source: https://docs.arct.cloud/api-reference/account-credit Credit balance, transactions and paying with account credit. Account credit is a prepaid USD balance. It pays a new server, a resize or an invoice in full; there are no partial payments. > [!NOTE] > > `400 credit_unavailable` means account credit isn't enabled for your account. ## Balance `GET /account` returns: | Field | Description | | - | - | | `credit_balance` | Account credit, USD. | | `credit_autopay` | `true` if credit pays due renewal invoices automatically. Card-billed servers keep charging the card. Set in the dashboard. | ## Transactions `GET /credit-transactions` lists your transactions, newest first, [paginated](/api-reference/pagination). ```bash theme={null} curl https://api.arct.cloud/v1/credit-transactions \ -H "Authorization: Bearer $ARCT_TOKEN" ``` | Field | Description | | - | - | | `type` | `topup`, `order_payment`, `invoice_payment`, `invoice_refund`, `adjustment`, `refund_payout`. | | `amount` | USD, signed: positive adds credit, negative spends or removes it. | | `balance_after` | Your credit right after this entry. | | `description` | Short text, such as the invoice number. | | `invoice_id`, `order_id` | Related invoice or order, else `null`. | ## Pay With Credit Needs a `read_write` token and a verified email (`403 email_not_verified`). Counts against the [Paid limit](/api-reference/rate-limits). | Action | Request | | - | - | | Create a server | `POST /servers` with `"payment_method": "credit"`. No saved card needed. | | Resize a server | `POST /servers/{server_id}/resize` with `"payment_method": "credit"`. Returns `200` with `status` `applied`. | | Pay an invoice | `POST /invoices/{invoice_id}/pay` with `{"payment_method": "credit"}`. | If credit doesn't cover the full amount: `402 insufficient_credit`, `details.shortfall` is the USD missing. Nothing is charged or reserved. ### Pay an Invoice Pays a `pending` invoice, including a failed card renewal. Returns the paid invoice with `payment_method` `credit`. ```bash theme={null} curl -X POST https://api.arct.cloud/v1/invoices/$INVOICE_ID/pay \ -H "Authorization: Bearer $ARCT_TOKEN" \ -H "Content-Type: application/json" \ -d '{"payment_method": "credit"}' ``` | Response | Meaning | | - | - | | `200` | Paid. | | `400 credit_unavailable` | Account credit isn't enabled for your account. | | `400 invoice_not_payable` | Not pending, or a resize invoice; pay a resize with `POST /servers/{server_id}/resize`. | | `402 insufficient_credit` | Add at least `details.shortfall` in credit. | | `404 not_found` | Unknown invoice, or not yours. | | `409 payment_in_progress` | A card payment for this invoice is still running. | | `503 billing_unavailable` | Nothing debited. Retry later. | ## Add Credit Add credit in the dashboard under **Billing > Account credits**, by card, Alipay or crypto. Adding credit, auto pay and credit refunds aren't in the API. # List Credit Transactions Source: https://docs.arct.cloud/api-reference/account-credit/list-credit-transactions /api-reference/openapi.json get /credit-transactions Returns your account credit transactions, newest first. # Get Your Account Source: https://docs.arct.cloud/api-reference/account/get-your-account /api-reference/openapi.json get /account Returns your account and the token that made the request. # Authentication Source: https://docs.arct.cloud/api-reference/authentication API tokens, access levels and auth errors. Send an API token in the `Authorization` header. Only `GET /openapi.json` works without one. ```bash theme={null} curl https://api.arct.cloud/v1/account \ -H "Authorization: Bearer $ARCT_TOKEN" ``` ## Create a Token * A valid payment is required for API access: a paid invoice or added credit. Without one you can't create tokens, and existing ones are refused with `account_not_eligible`. * Create one in **Settings** > **API Tokens** ([steps](/account/api-tokens)). The secret is shown once. * Expiry: **Never**, **30 days**, **90 days** or **1 year**. * The account owner gets an [email](/account/api-tokens#token-created-email) for each new token, without the secret. * The API can't manage tokens. ## Token Format `arct_` plus letters, digits, `-` and `_`, up to 100 characters; the dashboard shows the first 12. ## Access Levels | Scope | Dashboard label | Allows | | - | - | - | | `read` | Read only | Every `GET` endpoint. | | `read_write` | Read & write | Every endpoint, including charges and deletes. | Keep tokens server-side; use `read` tokens for read-only jobs. ## Auth Errors `401`: the token can't be used. `403`: the token is valid but the request isn't allowed. | HTTP | Code | Cause | | - | - | - | | `401` | `invalid_token` | Missing, malformed, unknown or deleted. | | `401` | `token_disabled` | Disabled; works again once re-enabled. | | `401` | `token_expired` | Expired. | | `403` | `account_disabled` | Account disabled. | | `403` | `account_not_eligible` | No valid payment on the account yet; pay an invoice or add credit. | | `403` | `api_access_disabled` | API not enabled for your account; contact support. | | `403` | `insufficient_scope` | `read` token on a write endpoint. | | `429` | `rate_limit_exceeded` | Too many [failed attempts](/api-reference/rate-limits#failed-authentication). | ## Rotate a Token Create a new token and switch to it. When the old token's **Last used** stops changing (it updates at most once a minute), disable it, then delete it. # List Datacenters Source: https://docs.arct.cloud/api-reference/catalog/list-datacenters /api-reference/openapi.json get /datacenters Returns the datacenters you can order servers in. `location` is the location code without a number, as used by older requests. # List Locations Source: https://docs.arct.cloud/api-reference/catalog/list-locations /api-reference/openapi.json get /locations Returns the locations you can order servers in. # List OS Images Source: https://docs.arct.cloud/api-reference/catalog/list-os-images /api-reference/openapi.json get /images Returns OS images per location. Filter with `datacenter` or `location`. # List Plans Source: https://docs.arct.cloud/api-reference/catalog/list-plans /api-reference/openapi.json get /plans Returns plans and monthly prices per location. Filter with `datacenter` or `location`. With `datacenter`, `in_stock` is that datacenter's stock. # CLI Source: https://docs.arct.cloud/api-reference/cli Install the Arct CLI and manage servers from your terminal. `arct` ships with the Python SDK in `arct-cloud` and requires Python 3.11+. The published preview is **`0.1.0rc3`**. Source preview **`0.1.0rc4`** adds datacenter discovery and placement, covering 23 API operations. Install the source preview below for datacenter commands; it is not yet on PyPI. Source and release notes are in [ArctCloud/sdk](https://github.com/ArctCloud/sdk). ## Install > [tab] macOS / Linux > > Install Python 3.11+ with virtual environment support, then run: > > ```bash theme={null} > curl -fsSL https://raw.githubusercontent.com/ArctCloud/sdk/main/install.sh | sh > export PATH="$HOME/.local/bin:$PATH" > arct --version > ``` > > The installer pins `arct-cloud==0.1.0rc3` in a private environment under `~/.local/share/arct/` and exposes `~/.local/bin/arct`, without sudo. It adds PATH setup to zsh or Bash startup files. Run the printed export in your current terminal; other shells require manual PATH setup. Your system Python packages stay separate. > [tab] Windows / Python environment > > Install into your chosen Python 3.11+ environment: > > ```powershell theme={null} > python -m pip install "arct-cloud==0.1.0rc3" > python -m arct --version > python -m arct --help > ``` > > The package also installs the `arct` console command. If its scripts directory is on PATH, use `arct`; otherwise replace `arct` below with `python -m arct`. On Windows, `py -3.11` can replace `python` to select the interpreter. These published installations report `0.1.0rc3` and do not include the datacenter commands below. The installer pin advances after a new package is published. ### Source Preview for Datacenter Commands With Git and Python 3.11+, create and activate a separate environment: ```bash macOS / Linux theme={null} python3 -m venv .venv . .venv/bin/activate python -m pip install "arct-cloud @ git+https://github.com/ArctCloud/sdk.git@987e036e5a81c1106bd0a6cc3d3f68ffabcead18#subdirectory=python" python -m arct --version ``` ```powershell Windows theme={null} py -3.11 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install "arct-cloud @ git+https://github.com/ArctCloud/sdk.git@987e036e5a81c1106bd0a6cc3d3f68ffabcead18#subdirectory=python" python -m arct --version ``` The source version reports `0.1.0rc4`. Keep this environment active for the examples below; its `arct` takes precedence over an older installer command. `python -m arct` explicitly uses the same interpreter as the source installation. ### Migrate, Update or Uninstall Commands, flags, credentials and named contexts remain compatible with the previous Go CLI. Historical [binary releases](https://github.com/ArctCloud/sdk/releases/tag/cli-v0.1.0-rc.2) remain available; new Go CLI binaries are no longer published. The installer refuses to replace an unrelated executable or symlink at `~/.local/bin/arct`. If your previous Go binary is there, move it aside before installing: ```bash theme={null} mv "$HOME/.local/bin/arct" "$HOME/.local/bin/arct-go" ``` After installation, check `command -v arct` and `arct --version`. If another old binary takes precedence, put `~/.local/bin` first on PATH or remove that old binary, then open a new terminal. Rerun the installer to update to its pinned release or repair an installation. Failed package installation preserves the working command; reruns do not duplicate shell profile entries. To uninstall the shell installation: ```bash theme={null} rm "$HOME/.local/bin/arct" rm -rf "$HOME/.local/share/arct" ``` Remove the installer-added PATH line from your shell profile if no longer needed. For a published `0.1.0rc3` package installation, update with `python -m pip install --upgrade "arct-cloud==0.1.0rc3"` or uninstall with `python -m pip uninstall arct-cloud`, using the same environment. Source-preview users should follow [the source instructions](#source-preview-for-datacenter-commands) in their source environment. Uninstalling retains saved credentials. Before uninstalling, `arct auth logout --context NAME` or `arct context delete NAME` removes a saved context; neither revokes the dashboard token. ## Authenticate and Start Read-Only Create a **Read only** token in [Settings > API Tokens](/account/api-tokens). Supply it through your environment or secret manager: ```bash macOS / Linux theme={null} export ARCT_TOKEN="arct_your_token_here" ``` ```powershell Windows theme={null} $env:ARCT_TOKEN = "arct_your_token_here" ``` ```bash theme={null} arct account get arct servers list arct datacenters list --all arct servers list --datacenter ams2 --output json arct locations list arct plans list --datacenter ams2 arct images list --datacenter ams2 ``` Datacenter codes such as `ams2` select placement; location codes such as `ams` group datacenters. Plan results list their supported `datacenters`; `--datacenter ams2` filters plans to that datacenter and scopes `in_stock` to its stock. `Server.datacenter` identifies placement and may be null until placement is known or for legacy servers. Deprecated `--location` remains compatible and prints one warning line to stderr. On creation it selects the location's default datacenter for the plan tier; on lists it retains location-wide filtering. For saved credentials, `arct auth login --context production` validates an existing token and stores it locally. Input is hidden on an interactive terminal. `arct context use production` selects it; `arct auth status` shows the source without revealing the token. `ARCT_TOKEN` overrides saved contexts. There is no token command-line flag. `arct auth logout --context production` removes local credentials; it does not revoke the token. Create, disable or delete tokens in the dashboard. ```bash theme={null} arct context list arct context use production arct context delete unused-context ``` `--context NAME` selects a saved context; `ARCT_TOKEN` overrides its token. The credential JSON schema (`active`, named `contexts`, `token`, optional `base_url`) and locations are unchanged. `$XDG_CONFIG_HOME/arct/config.json` takes precedence when set; otherwise the file is `~/.config/arct/config.json` on Linux, `~/Library/Application Support/arct/config.json` on macOS or `%APPDATA%\arct\config.json` on Windows. POSIX credentials use file mode `0600` and directory mode `0700`; Windows protects them with an ACL for the current user and SYSTEM. The default endpoint is `https://api.arct.cloud/v1`. `--base-url` or `ARCT_BASE_URL` selects another HTTPS endpoint; plain HTTP is allowed only for explicit localhost tests. Redirects are rejected. ## Create and Manage Servers > [!WARNING] > > Use a `read_write` token for mutations. Creation and resize charge the saved card. Paid/destructive operations require confirmation; `--yes` explicitly confirms them for automation. Noninteractive commands without required confirmation fail before mutation. List datacenters, plans and images first. Add a public key and select its UUID: ```bash theme={null} arct ssh-keys create --name my-laptop --public-key-file ~/.ssh/id_ed25519.pub arct ssh-keys list arct servers create --hostname web-1 --datacenter ams2 --plan hvm.nano \ --image IMAGE_UUID --ssh-key KEY_UUID --billing-period monthly --yes --wait ``` Creation requires `--hostname`, `--plan`, `--image` and either `--datacenter` or deprecated `--location`. If both placement fields are supplied, they must agree. `422 datacenter_mismatch` means the datacenter and location conflict; `400 datacenter_unavailable` means the datacenter does not offer the selected plan. `hvm.nano` is an Amsterdam 2 plan; use `arct plans list --datacenter ams2` to choose another. Replace `TARGET_PLAN` with an eligible slug from `resize-options`, and `IMAGE_UUID`, `KEY_UUID` and `SERVER_UUID` with actual resource UUIDs. Image IDs are location-specific; choose an image compatible with the plan. Once running, connect using the returned `login_user` and `ipv4`: `ssh -i ~/.ssh/id_ed25519 USER@IP_ADDRESS`. See [SSH access](/compute/virtual-machines/connect-ssh). ```bash theme={null} arct servers get SERVER_UUID arct servers stop SERVER_UUID --wait arct servers start SERVER_UUID --wait arct servers restart SERVER_UUID --wait arct servers update SERVER_UUID --delete-protection=true ``` Reinstall wipes the disk. Choose a compatible image and explicitly confirm: ```bash theme={null} arct servers reinstall SERVER_UUID --image IMAGE_UUID --ssh-key KEY_UUID --yes --wait ``` ### Accepted Versus Completed Without `--wait`, exit `0` can mean **accepted**, rather than finished. Creation returns HTTP `201`; start/stop/restart/reinstall return HTTP `202`. `--wait` polls every 5 seconds, with a default 600-second deadline. Override it with `--timeout 15m` or `--timeout 900`. ```bash theme={null} arct servers wait SERVER_UUID --status running --timeout 15m ``` Use `--wait` on the original restart/reinstall command to retain transition tracking. A separate `servers wait` checks current status; it cannot prove that an earlier restart completed. A stale initial `running` observation is not accepted as completion by the action waiter. Pre-orders or an unobserved transition can time out as unverified. Timeouts and interruption stop local waiting; an accepted remote action can continue. Successful create/start/stop/restart/reinstall and status waits show final server fields in table output; JSON preserves the original result with `final_server`. Resize waits add `final_resize_options`; immediate deletion adds `deleted: true`. A wait failure retains the original result with `wait_error` and exits nonzero. One-time passwords stay masked unless you explicitly add `--show-password` to create/reinstall, including after waiting. Tokens remain redacted even with that flag. ### Resize Stop the server and wait for `stopped`, then inspect the eligible plans and quote: ```bash theme={null} arct servers stop SERVER_UUID --wait arct servers resize-options SERVER_UUID arct servers resize SERVER_UUID --plan TARGET_PLAN --expected-amount 4.12 --yes --wait ``` Replace `4.12` with the exact `amount_due_today` you reviewed. An omitted `--expected-amount` obtains a quote before confirmation and submits that exact amount unchanged; `price_changed` requires a new decision and never silently substitutes a new price. HTTP `200 applied` and `202 pending_payment` are distinct. Resolve any required payment in the dashboard and confirm the requested plan is applied before running `arct servers start SERVER_UUID --wait`. Resize does not stop or start a server automatically. ### Delete or Schedule Deletion Immediate deletion wipes the disk and cannot be undone. Delete protection must be off first: ```bash theme={null} arct servers update SERVER_UUID --delete-protection=false arct servers delete SERVER_UUID --yes --wait ``` Immediate `--wait` finishes after the acknowledged deletion returns `404` on polling. To keep the server until its paid period ends instead: ```bash theme={null} arct servers delete SERVER_UUID --at-period-end --yes arct servers cancel-deletion SERVER_UUID --yes ``` Scheduled deletion reports `cancel_at` and does not support `--wait`. Canceling it restores normal renewal. See [deletion and billing behavior](/api-reference/creating-servers#delete-a-server). ## Output, Pagination and Errors Lists fetch one page by default. `--page` and `--per-page` select a page; `--all` retrieves every page. Single-page JSON preserves `data` and `pagination`; `--all --output json` returns an array. ```bash theme={null} arct servers list --page 2 --per-page 50 --output json arct servers list --all --columns id,hostname,status --no-header arct invoices list --all --output json ``` `--columns` and `--no-header` apply to table output. Results go to stdout; prompts, progress and errors go to stderr. JSON errors are structured and redacted. See [API errors](/api-reference/errors), [pagination](/api-reference/pagination) and [rate limits](/api-reference/rate-limits). | Exit | Meaning | | - | - | | `0` | Success or accepted operation | | `1` | API or network error | | `2` | Invalid input or missing confirmation | | `3` | Timeout, uncertain outcome or unknown charge | | `130` | Interrupted | Charge-unknown markers (`order_intent_id` or `payment_pending`) are never automatically retried. Preserve the support identifiers and verify billing before repeating a purchase. A lost response or matching hostname does not prove a successful order. ## Command Controls Global flags may appear before or after the resource/action. `arct --help` lists resources; `arct RESOURCE ACTION --help` shows command flags. | Command | Request controls | | - | - | | `servers list` | `--status`, `--datacenter`, `--location` | | `plans list`, `images list` | `--datacenter`, `--location` | | Every API `list` | `--page`, `--per-page`, `--all` | | `servers create` | `--hostname`, `--datacenter` or deprecated `--location`, `--plan`, `--image`, `--billing-period`, repeated `--ssh-key`, `--coupon-code` or `--coupon-code-null`, `--enable-backups[=false]` | | `servers update ID` | `--hostname`, `--delete-protection[=false]`, repeated `--label` | | `servers delete ID` | `--at-period-end[=false]`, `--yes`, immediate `--wait` | | `servers reinstall ID` | `--image`, `--hostname`, repeated `--ssh-key`, `--yes` | | `servers resize ID` | `--plan`, `--expected-amount`, `--yes` | | `ssh-keys create` | `--name`, `--public-key` or `--public-key-file PATH` (`-` reads stdin) | | `servers wait ID` | `--status`, `--timeout` | Use `--ssh-key ''` for an explicit empty key array (password access where supported), `--label ''` to clear labels, and `--coupon-code-null` for a null coupon. Omitted fields remain omitted; `--enable-backups=false` and `--delete-protection=false` send explicit false. The CLI does not expose a null resize amount to opt out of price protection. ## Commands and API Boundaries The CLI's API resources are `account`, `servers`, `datacenters`, `locations`, `plans`, `images`, `ssh-keys` and `invoices`. Local `auth` and `context` commands manage saved credentials. `servers create --enable-backups` can enable automatic backups where supported. There are **no backup/snapshot management commands or endpoints**; use the [dashboard](/compute/virtual-machines/backups-snapshots). Cards, token issuance/revocation, password resets and VNC are also dashboard operations. The CLI has no invoice-payment command; the API supports [paying invoices with account credit](/api-reference/account-credit#pay-an-invoice). # Creating Servers Source: https://docs.arct.cloud/api-reference/creating-servers Create, reinstall, resize and delete servers: payment and password rules. `POST /servers` needs a `read_write` token. It charges the first billing period to your default card, else your first saved card, or to [account credit](/api-reference/account-credit), then builds the server. ## Before You Start * A verified email address, else `403 email_not_verified`. * A saved card, else `402 no_payment_method`; or enough account credit with `payment_method: credit`. * SSH keys added with `POST /ssh-keys`. * `GET /datacenters`, then `GET /plans?datacenter=ams2` and `GET /images?datacenter=ams2`. ## Create a Server ```bash theme={null} curl -X POST https://api.arct.cloud/v1/servers \ -H "Authorization: Bearer $ARCT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "hostname": "web-1", "datacenter": "ams2", "plan": "hvm.small", "image_id": "IMAGE_ID", "ssh_key_ids": ["SSH_KEY_ID"] }' ``` | Field | Required | Rules | | - | - | - | | `hostname` | Yes | 1 to 63 letters, digits, hyphens; no hyphen at either end. | | `datacenter` | Unless `location` is supplied | Datacenter `code` from `GET /datacenters`, such as `ams2`. Any case. | | `location` | Unless `datacenter` is supplied | Deprecated. Location code without a number, such as `ams`. Without `datacenter`, the server goes to the location's default datacenter for the plan's tier. With both, they must match. | | `plan` | Yes | Plan `slug` from `GET /plans`. | | `image_id` | Yes | Image ID from `GET /images` for the same datacenter. Offered OSes differ per location; see [Images](/api-reference/images). | | `billing_period` | No | `monthly` (default), `quarterly`, `semi_annual`, `yearly`. Pre-order locations: `semi_annual` or `yearly`. | | `ssh_key_ids` | No | Up to 20 of your SSH key IDs. See [Login Password](#login-password). | | `coupon_code` | No | Promo code, up to 64 characters. See [Promo Codes](#promo-codes). | | `enable_backups` | No | `true` adds automatic backups for 20% of the plan price, where `backups_available` is `true`. | | `payment_method` | No | `card` (default) or `credit`. `credit` pays from account credit; no card needed. | There is no card field. To charge another card, make it the default in the dashboard. Returns `201`: ```json theme={null} { "order": { "id": "9b1e3d5f-7a2c-4e6b-8d0f-1c3e5a7b9d2f", "order_number": "ORD-20261013-1A2B3C", "status": "paid", "payment_method": "card", "amount": 5.99, "server_id": "4f6c2a8e-1d3b-4c5a-9e7f-0b2d4c6e8a1f" }, "server": {"id": "4f6c2a8e-1d3b-4c5a-9e7f-0b2d4c6e8a1f", "hostname": "web-1", "status": "provisioning"}, "password": null } ``` `server` can be `null` until it is recorded; find it with `GET /servers`. At a pre-order location, `status` is `pre_order` until deployed. ## Login Password `password` is the login for `server.login_user`: | Image | `ssh_key_ids` | `password` | | - | - | - | | Windows | Ignored | Set (user `Administrator`) | | Linux | `[]` | Set | | Linux | Omitted, no saved keys | Set; keys saved later aren't installed | | Linux | Omitted, saved keys | `null`; all saved keys installed | | Linux | Your key IDs | `null`; those keys installed | * Shown only in this response and the server-ready email. Sent with `Cache-Control: no-store`. * `null` at pre-order locations or for a delayed build; it is emailed once built. * A build retried by support gets a new password by email. * If Windows password setup fails, the email says so; set one in the [VNC Console](/compute/virtual-machines/manage#vnc-console). Connect with [SSH](/compute/virtual-machines/connect-ssh) or [RDP](/compute/virtual-machines/connect-rdp) once `status` is `running`. Reset a lost password in the dashboard. ## Promo Codes Send the code as `coupon_code`. * Checked before any charge. A discount lowers today's charge. * A code that makes the first payment free sets `payment_method` to `promo`. * A recurring code also discounts renewals. ## Create Errors Only `409 payment_pending` and `500` with `details.order_intent_id` may have charged your card: don't retry, contact support with that ID. | Response | Action | | - | - | | `400 bad_request` | Fix the request; see `message`. | | `400 invalid_promo_code` | Fix or remove `coupon_code`. | | `400 credit_unavailable` | Use `card`; account credit isn't enabled for your account. | | `402 authentication_required` | Deploy from the dashboard. | | `402 card_declined` | Make another card the default. | | `402 insufficient_credit` | Add at least `details.shortfall` in credit in the dashboard, or use `card`. | | `402 no_payment_method` | Add a card in the dashboard. | | `402 payment_failed` | Check the card, or retry later. | | `403 email_not_verified` | Verify your email, then retry. | | `403 orders_disabled`, `503 service_unavailable` | Retry later. | | `404 not_found` | Send only your own SSH key IDs. | | `409 hostname_taken` | See [Safe Retries](#safe-retries). | | `400 datacenter_unavailable` | Pick a datacenter whose `GET /plans?datacenter=` lists the plan. | | `409 out_of_stock` | Choose another plan or datacenter. | | `422 datacenter_mismatch` | Send `datacenter` only, or a `location` that contains it. | | `409 promo_changed` | Resend the request as is. | | `409 payment_pending` | Don't retry. Contact support. | | `500 internal_error` | Retry unless `details.order_intent_id` is set. | ## Follow Provisioning Poll `GET /servers/{server_id}` every 5 to 10 seconds until `status` is `running`; `ipv4` is set by then. ```bash theme={null} curl https://api.arct.cloud/v1/servers/$SERVER_ID \ -H "Authorization: Bearer $ARCT_TOKEN" ``` ## Safe Retries Retry `POST /servers` with the same `hostname`; it can't create a second server. * A live server or open order with that hostname (any case) returns `409 hostname_taken`. * After `402`, `409 out_of_stock` or `503` nothing is reserved, so a retry can create the server. * A deleted server frees its hostname. ## Reinstall a Server `POST /servers/{server_id}/reinstall` wipes the disk and installs `image_id` from the server's location. The server must be running or stopped. Returns `202` with a new `password` ([same rules](#login-password)); the old one stops working. ```bash theme={null} curl -X POST https://api.arct.cloud/v1/servers/$SERVER_ID/reinstall \ -H "Authorization: Bearer $ARCT_TOKEN" \ -H "Content-Type: application/json" \ -d '{"image_id": "IMAGE_ID", "ssh_key_ids": []}' ``` ## Resize a Server A resize moves a stopped server to a bigger plan. The API charges the prorated difference for the rest of the period to the server's billing card, else your default card, or to account credit with `payment_method: credit`. A recurring promo carries over. With backups on, `amount_due_today` includes the backups difference (20% of the plan price), and `addon_period` is the backups price per period. 1. Stop the server; wait until `status` is `stopped`. 2. Call `GET /servers/{server_id}/resize-options`. Check each plan's `eligible` and `amount_due_today`, or `blocked_code` when `can_resize` is `false`. 3. Send `POST /servers/{server_id}/resize` with `plan` and, optionally, `expected_amount` set to the quoted `amount_due_today` and `payment_method` from `payment_methods`. 4. Start the server. ```bash theme={null} curl -X POST https://api.arct.cloud/v1/servers/$SERVER_ID/resize \ -H "Authorization: Bearer $ARCT_TOKEN" \ -H "Content-Type: application/json" \ -d '{"plan": "vm.medium", "expected_amount": 4.12}' ``` ### Resize Outcomes | Response | Meaning | | - | - | | `200` | Paid. `status` is `applied`. | | `202` | `status` is `pending_payment`; applies once the payment clears. | | `400 invalid_plan`, `ineligible` | Not a plan this server can move to. | | `400 credit_unavailable` | Account credit isn't enabled for your account. | | `402 authentication_required` | Pay `details.hosted_invoice_url` within 1 hour; applies once paid. | | `402 card_declined` | Bank declined the charge. | | `402 no_payment_method` | No saved card. | | `402 insufficient_credit` | Account credit is short by `details.shortfall`. | | `409 price_changed` | New quote in `details.amount`. | | `409 vm_state` | Server isn't stopped, or is suspended. | | `409 conflict` | Server is a pre-order. | | `409 pending` | Another resize awaits payment. | | `409 unpaid_invoice`, `subscription_not_active` | Pay the server's open invoice first. | | `409 cancel_scheduled` | Undo cancel at period end first. | | `409 cancelled` | Another session cancelled this resize. | | `409 refund_pending` | Charged, but the server was deleted; support refunds `details.invoice_id`. | | `403 billing_mismatch`, `409 unsupported_subscription`, `unknown_plan`, `unknown_price`, `no_billing_period` | Contact support. | | `503 service_unavailable`, `billing_unavailable` | Retry later. | `402`, `409 price_changed` and `409 cancelled` charge nothing. ## Delete a Server `DELETE /servers/{server_id}` deletes the server and wipes its disk at once. Returns `204`. Can't be undone. ```bash theme={null} curl -X DELETE https://api.arct.cloud/v1/servers/$SERVER_ID \ -H "Authorization: Bearer $ARCT_TOKEN" ``` * Renewals stop; an unstarted renewal invoice is cancelled. * Paid time isn't refunded. * Backups are deleted (used backup days are billed); snapshots are kept. Returns `409 conflict` when: * Delete protection is on. Turn it off with `PATCH /servers/{server_id}` and `{"delete_protection": false}`. * A backup, snapshot or restore is running. * The server is a pre-order. * The server is already being deleted. ### Delete at Period End `DELETE /servers/{server_id}?at_period_end=true` keeps the server until its paid period ends, then deletes it. Nothing renews. Returns `200` with the server; `cancel_at` is the deletion date. Calling it again changes nothing. ```bash theme={null} curl -X DELETE "https://api.arct.cloud/v1/servers/$SERVER_ID?at_period_end=true" \ -H "Authorization: Bearer $ARCT_TOKEN" ``` Also returns `409 conflict` when an invoice is unpaid, a resize is pending, a renewal is in progress, or no paid time is left. `503 service_unavailable` means billing is unreachable; retry later. ### Cancel a Scheduled Deletion `POST /servers/{server_id}/cancel-deletion` keeps the server; it renews as before. Returns `200` with the server and `cancel_at: null`. A server with nothing scheduled is returned unchanged. ```bash theme={null} curl -X POST https://api.arct.cloud/v1/servers/$SERVER_ID/cancel-deletion \ -H "Authorization: Bearer $ARCT_TOKEN" ``` Returns `409 conflict` when the server is already being deleted or its period has ended. # Errors Source: https://docs.arct.cloud/api-reference/errors Error format, error codes and what to retry. Every error returns the same JSON body: ```json theme={null} { "error": { "code": "hostname_taken", "message": "A server or order on your account already uses this hostname.", "details": null } } ``` | Field | Description | | - | - | | `code` | Stable code. Branch on it. | | `message` | For people. May change. | | `details` | Extra data or `null`, such as `details.amount` on `409 price_changed`. | New codes may be added; handle unknown ones by HTTP status. ## Validation Errors Invalid input returns `422 validation_error`, with each problem in `details.fields`; `field` is `body.`, `query.` or `path.`. ```json theme={null} { "error": { "code": "validation_error", "message": "The request has invalid fields.", "details": { "fields": [ {"field": "body.hostname", "message": "String should match pattern '^[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?$'"} ] } } } ``` Unknown body fields and `null` for a field that doesn't take it also return `422`; omit the field instead. ## Error Codes | HTTP | Code | Description | | - | - | - | | `400` | `bad_request` | Not possible as sent; `message` says why. | | `400` | `invalid_promo_code` | Unknown, expired or not valid for this order. | | `400` | `invalid_plan`, `ineligible` | Can't resize to this plan. | | `400` | `credit_unavailable` | Account credit isn't enabled for your account. | | `400` | `datacenter_unavailable` | Datacenter doesn't offer this plan. | | `400` | `invoice_not_payable` | Invoice isn't pending, or is a resize invoice. | | `401` | `invalid_token` | Missing, malformed, unknown or deleted. | | `401` | `token_disabled` | Token disabled. | | `401` | `token_expired` | Token expired. | | `402` | `authentication_required` | Bank requires 3D Secure. | | `402` | `card_declined` | Bank declined the charge. | | `402` | `insufficient_credit` | Account credit is short by `details.shortfall` (USD). | | `402` | `no_payment_method` | No saved card. | | `402` | `payment_failed` | Card payment couldn't start. | | `403` | `account_disabled` | Account disabled. | | `403` | `account_not_eligible` | No valid payment on the account yet. | | `403` | `api_access_disabled` | API isn't enabled for your account. | | `403` | `billing_mismatch` | Resize only: server billing doesn't match your account. | | `403` | `email_not_verified` | Email not verified. | | `403` | `insufficient_scope` | `read` token on a write endpoint. | | `403` | `orders_disabled` | New orders are paused. | | `404` | `not_found` | Unknown path or ID, or another account's ID. | | `405` | `method_not_allowed` | Path doesn't take this method. | | `409` | `conflict` | Current state doesn't allow this; each endpoint lists its causes. | | `409` | `hostname_taken` | A server or open order uses this hostname. | | `409` | `out_of_stock` | Plan sold out at this datacenter. | | `409` | `payment_in_progress` | A card payment for this invoice is still running. | | `409` | `payment_pending` | Charge unknown; don't retry. See [Create Errors](/api-reference/creating-servers#create-errors). | | `409` | `promo_changed` | Promo code no longer makes the order free. | | `409` | `price_changed`, `vm_state`, `pending`, `unpaid_invoice`, `subscription_not_active`, `cancel_scheduled`, `cancelled`, `refund_pending`, `unsupported_subscription`, `unknown_plan`, `unknown_price`, `no_billing_period` | Resize refused. See [Resize Outcomes](/api-reference/creating-servers#resize-outcomes). | | `413` | `payload_too_large` | Request body over 64 KB. | | `422` | `datacenter_mismatch` | `datacenter` isn't in `location`. | | `422` | `validation_error` | Invalid body, query or path field. | | `429` | `rate_limit_exceeded` | Rate limit reached. | | `500` | `internal_error` | Unexpected server error. | | `503` | `billing_unavailable` | Resize or invoice payment: billing is briefly unavailable. | | `503` | `service_unavailable` | Host node or card payments unavailable. | No `402` charges your card. ## What to Retry | Response | Action | | - | - | | Any error with `details.order_intent_id` | Don't retry. Contact support with that ID. | | `429` | Wait `Retry-After` seconds, then retry. | | Network error, `500` or `503` | Retry with backoff. See [Safe Retries](/api-reference/creating-servers#safe-retries). | | `409 promo_changed` | Send the same request again. | | Any other `4xx` | Fix the request first. | # Images Source: https://docs.arct.cloud/api-reference/images Operating systems you can deploy, and where they're offered. An image is the operating system for `POST /servers` and reinstall. ## Operating Systems | OS | Versions | Login user | | - | - | - | | Ubuntu | 22.04 LTS, 24.04 LTS, 26.04 LTS | `ubuntu` | | Debian | 12 (Bookworm), 13 (Trixie) | `debian` | | CentOS Stream | 9, 10 | `cloud-user` | | AlmaLinux | 9, 10 | `almalinux` | | Rocky Linux | 9, 10 | `rocky` | | Fedora | 43, 44 | `fedora` | | Windows Server | 2022 | `Administrator` | > [!NOTE] > > Availability differs per location and plan. List what a datacenter offers before you create a server. ## List Images ```bash theme={null} curl "https://api.arct.cloud/v1/images?datacenter=fra1" \ -H "Authorization: Bearer $ARCT_TOKEN" ``` ```json theme={null} { "data": [ { "id": "8d3e5f7a-2b4c-4e6d-9f1a-3c5e7a9b1d2f", "name": "Rocky Linux", "version": "9", "display_name": "Rocky Linux 9", "location": "fra", "allowed_plans": ["cvm.micro", "cvm.small", "cvm.medium"] } ], "pagination": {"page": 1, "per_page": 20, "total": 1, "total_pages": 1} } ``` | Field | Notes | | - | - | | `id` | Differs per location. Use the ID from the server's datacenter. | | `allowed_plans` | Plans the image runs on; empty means every plan. Another plan returns `400 bad_request`. | * Filter with `datacenter` or `location`; see [Pagination](/api-reference/pagination) for `page` and `per_page`. * `GET /servers/{server_id}` returns the account to sign in with as `login_user`. # Introduction Source: https://docs.arct.cloud/api-reference/introduction Manage Arct Cloud servers over a REST API. The Arct Cloud API manages servers, SSH keys, invoices and the catalog. Use the [Python and TypeScript SDKs](/api-reference/sdks) in applications or the [Arct CLI](/api-reference/cli) in your terminal. ```bash theme={null} export ARCT_TOKEN="arct_your_token_here" curl https://api.arct.cloud/v1/account \ -H "Authorization: Bearer $ARCT_TOKEN" ``` > [!NOTE] > > `403 api_access_disabled` means the API isn't enabled for your account yet; contact [support](/account/support-tickets). ## Base URL ```text theme={null} https://api.arct.cloud/v1 ``` HTTPS only. JSON request and response bodies. ## Before You Start * A valid payment is required for API access: a paid invoice or added credit. * Create an API token; see [Authentication](/api-reference/authentication). * `POST /servers` and resizes charge a saved card or [account credit](/api-reference/account-credit); see [Creating Servers](/api-reference/creating-servers). ## What You Can Do | Area | `read` token (`GET`) | `read_write` token adds | | - | - | - | | Account | `/account`, `/credit-transactions` | | | Catalog | `/datacenters`, `/locations`, `/plans`, `/images` | | | Servers | `/servers`, `/servers/{server_id}`, `/servers/{server_id}/resize-options` | `POST /servers`, `PATCH` and `DELETE /servers/{server_id}`, start, stop, restart, reinstall, resize, cancel scheduled deletion | | SSH Keys | `/ssh-keys`, `/ssh-keys/{key_id}` | `POST /ssh-keys`, `DELETE /ssh-keys/{key_id}` | | Invoices | `/invoices`, `/invoices/{invoice_id}` | `POST /invoices/{invoice_id}/pay` | ## Conventions | Topic | Rule | | - | - | | IDs | UUIDs. Datacenters use `code` such as `ams1` (any case in, lowercase out); plans use `slug`. `location` codes without a number are deprecated. | | Money | USD. | | Timestamps | ISO 8601, UTC. | | Lists | [Paginated](/api-reference/pagination) with `page` and `per_page`. | | Errors | One [envelope](/api-reference/errors) with a stable `code`. | | Limits | [Rate limits](/api-reference/rate-limits) per token; writes also per account. | ## OpenAPI Specification Fetch it without a token. ```bash theme={null} curl https://api.arct.cloud/v1/openapi.json ``` ## Not in the API Dashboard only: password reset, paying invoices by card, adding credit, cards and the default card, backup/snapshot management, API tokens, the VNC console, crypto payments. The API supports [scheduled deletion and cancellation](/api-reference/creating-servers#delete-at-period-end), and server creation can enable automatic backups. No webhooks; poll `GET /servers/{server_id}`. # Get an Invoice Source: https://docs.arct.cloud/api-reference/invoices/get-an-invoice /api-reference/openapi.json get /invoices/{invoice_id} Returns one invoice with its line items. # List Invoices Source: https://docs.arct.cloud/api-reference/invoices/list-invoices /api-reference/openapi.json get /invoices Returns your invoices, newest first. # Pay an Invoice Source: https://docs.arct.cloud/api-reference/invoices/pay-an-invoice /api-reference/openapi.json post /invoices/{invoice_id}/pay Pays a pending invoice in full from account credit and returns the paid invoice. Add credit in the dashboard under Billing > Account credits. # Pagination Source: https://docs.arct.cloud/api-reference/pagination Page through list endpoints. All list endpoints are paginated: `GET /servers`, `GET /invoices`, `GET /ssh-keys`, `GET /credit-transactions`, `GET /datacenters`, `GET /locations`, `GET /plans` and `GET /images`. ## Query Parameters | Parameter | Default | Range | | - | - | - | | `page` | `1` | 1 to 100000 | | `per_page` | `20` | 1 to 100 | Out of range returns `422 validation_error`. ```bash theme={null} curl "https://api.arct.cloud/v1/servers?page=2&per_page=50" \ -H "Authorization: Bearer $ARCT_TOKEN" ``` ## Response ```json theme={null} { "data": [{"id": "4f6c2a8e-1d3b-4c5a-9e7f-0b2d4c6e8a1f"}], "pagination": { "page": 2, "per_page": 50, "total": 51, "total_pages": 2 } } ``` * A page past the end returns an empty `data`. * An empty list has `total_pages` `0`. * Single resources aren't wrapped in `data`. To fetch all, increase `page` up to `pagination.total_pages`. # Rate Limits Source: https://docs.arct.cloud/api-reference/rate-limits Request limits per token and account, and 429 handling. Limits apply per token; write and paid limits also apply per account, so extra tokens don't add capacity. Dashboard use doesn't count. ## Limits | Limit | Allowed | Applies to | | - | - | - | | Read | 120 per minute | `GET` endpoints | | Write | 30 per minute | `POST`, `PATCH`, `DELETE` | | Paid | 5 per minute, 20 per hour | `POST /servers`, `POST /servers/{server_id}/resize`, `POST /invoices/{invoice_id}/pay` (also count as writes) | ## Failed Authentication More than 20 failed authentications per minute from one IP return `429 rate_limit_exceeded` instead of `401`. Valid tokens are not affected. ## When You Hit a Limit ```text theme={null} HTTP/1.1 429 Too Many Requests Retry-After: 42 ``` ```json theme={null} { "error": { "code": "rate_limit_exceeded", "message": "Too many requests. Retry in 42 seconds.", "details": {"limit": "120 per 1 minute"} } } ``` Wait `Retry-After` seconds, then retry. `details.limit` names the limit; `details` is `null` for failed authentications. # SDKs Source: https://docs.arct.cloud/api-reference/sdks Use the Python and TypeScript SDKs to manage Arct Cloud resources. The Python and TypeScript SDKs provide typed clients for the Arct Cloud API. Source, examples and changelogs are in [ArctCloud/sdk](https://github.com/ArctCloud/sdk). The Python package also includes `arct` and `python -m arct` for terminal automation; see the [CLI installation guide](/api-reference/cli), including the macOS/Linux shell installer. ## Install the Preview | SDK | Published preview | Runtime | | - | - | - | | Python, `arct-cloud` | `0.1.0rc3` | Python 3.11+ | | TypeScript / JavaScript, `@arct-cloud/sdk` | `0.1.0-rc.4` | Node.js 22+, ESM | Install an exact preview from [PyPI](https://pypi.org/project/arct-cloud/0.1.0rc3/) or [npm](https://www.npmjs.com/package/@arct-cloud/sdk): ```bash Python theme={null} python -m pip install "arct-cloud==0.1.0rc3" ``` ```bash TypeScript / JavaScript theme={null} npm install --save-exact @arct-cloud/sdk@0.1.0-rc.4 ``` ### Install from Source > [!NOTE] > > The datacenter examples below require the merged source versions: Python `0.1.0rc4` or TypeScript `0.1.0-rc.5`. Those versions are not yet published to PyPI or npm; the published previews above do not include datacenter support. With Git installed, clone the source into your project directory: ```bash theme={null} git clone https://github.com/ArctCloud/sdk.git arct-sdk ``` ```bash Python theme={null} python -m pip install ./arct-sdk/python ``` ```bash TypeScript / JavaScript theme={null} npm --prefix arct-sdk/typescript ci npm --prefix arct-sdk/typescript run build npm install ./arct-sdk/typescript ``` The TypeScript commands build the local package before adding it to your application. Keep that checkout while using a local file dependency. ## Authenticate and Read Resources Create a token in [Settings > API Tokens](/account/api-tokens). Choose **Read only** for queries and **Read & write** for mutations. Supply it through your environment or secret manager: ```bash macOS / Linux theme={null} export ARCT_TOKEN="arct_your_token_here" ``` ```powershell Windows theme={null} $env:ARCT_TOKEN = "arct_your_token_here" ``` Explicit `token=` in Python or `{ token }` in TypeScript overrides `ARCT_TOKEN`. Both SDKs use `https://api.arct.cloud/v1` by default. Keep tokens server-side; never embed them in browser code. > [tab] Python > > ```python theme={null} > from arct import Arct > > with Arct() as client: > print(client.account.get().id) > for datacenter in client.datacenters.list(): > print(datacenter.code, datacenter.name) > for plan in client.plans.list(datacenter="ams2"): > print(plan.slug, plan.in_stock) > for server in client.servers.list(datacenter="ams2"): > print(server.id, server.hostname, server.status) > page = client.images.list_page(datacenter="ams2", page=1, per_page=20) > print(page.pagination.total) > ``` > [tab] Async Python > > ```python theme={null} > import asyncio > from arct import AsyncArct > > async def main(): > async with AsyncArct() as client: > print((await client.account.get()).id) > async for datacenter in client.datacenters.list(): > print(datacenter.code, datacenter.name) > async for plan in client.plans.list(datacenter="ams2"): > print(plan.slug, plan.in_stock) > async for server in client.servers.list(datacenter="ams2"): > print(server.id, server.hostname, server.status) > page = await client.images.list_page(datacenter="ams2", page=1, per_page=20) > print(page.pagination.total) > > asyncio.run(main()) > ``` > [tab] TypeScript / JavaScript > > ```javascript theme={null} > import { Arct } from '@arct-cloud/sdk'; > > const client = new Arct(); > console.log((await client.account.get()).id); > for await (const datacenter of client.datacenters.list()) { > console.log(datacenter.code, datacenter.name); > } > for await (const plan of client.plans.list({ datacenter: 'ams2' })) { > console.log(plan.slug, plan.in_stock); > } > for await (const server of client.servers.list({ datacenter: 'ams2' })) { > console.log(server.id, server.hostname, server.status); > } > const page = await client.images.listPage({ datacenter: 'ams2', page: 1, perPage: 20 }); > console.log(page.pagination.total); > ``` `list()` lazily retrieves every page, using 100 items per page by default and preserving filters. Python `list_page()` and TypeScript `listPage()` return one page with its pagination metadata. Page-number results can change while resources are being added or removed. See [Pagination](/api-reference/pagination). Discover codes with `datacenters.list()`. Datacenter codes are case-insensitive and match `^[A-Za-z]{2,5}[0-9]{1,2}$`. Server, plan and image lists accept `datacenter`; a plan's `in_stock` reflects the selected datacenter when that filter is supplied. `locations.list()` remains available. Legacy `location` fields and filters remain accepted but deprecated; Python emits `DeprecationWarning` when they are supplied. ## Create and Wait for a Server > [!WARNING] > > These examples charge the saved card and require a `read_write` token. SDK methods do not prompt. Review the datacenter, plan and billing period before running a creation example. These examples use datacenter `ams2` and plan `hvm.nano`. Confirm the plan is available with `plans.list(datacenter="ams2")` in Python or `plans.list({ datacenter: 'ams2' })` in TypeScript. Choose a compatible image filtered by the same datacenter and a saved public key matching your local private key. These examples use the saved key name `my-laptop`; add your public key in [SSH Keys](/compute/virtual-machines/ssh-keys) first. Replace `TARGET_PLAN` below with the target resize plan. Creation requires `hostname`, `plan`, `image_id`, and at least one of `datacenter` or legacy `location`. Both placement fields may be supplied when they agree. An unavailable plan/datacenter combination returns `400 datacenter_unavailable`; conflicting placement fields return `422 datacenter_mismatch`. > [tab] Python > > ```python theme={null} > from arct import Arct > > with Arct() as client: > datacenter, plan = "ams2", "hvm.nano" > image = next( > image for image in client.images.list(datacenter=datacenter) > if "ubuntu" in image.name.lower() > and (not image.allowed_plans or plan in image.allowed_plans) > ) > key = next(key for key in client.ssh_keys.list() if key.name == "my-laptop") > result = client.servers.create( > hostname="web-1", datacenter=datacenter, plan=plan, > image_id=image.id, ssh_key_ids=[key.id], billing_period="monthly", > ) > server = client.servers.wait_until(result, "running", timeout=600) > print(f"ssh -i ~/.ssh/id_ed25519 {server.login_user}@{server.ipv4}") > ``` > [tab] TypeScript / JavaScript > > ```javascript theme={null} > import { Arct } from '@arct-cloud/sdk'; > > const client = new Arct(); > const datacenter = 'ams2'; > const plan = 'hvm.nano'; > const images = await Array.fromAsync(client.images.list({ datacenter })); > const image = images.find(image => image.name.toLowerCase().includes('ubuntu') && > (image.allowed_plans.length === 0 || image.allowed_plans.includes(plan))); > const keys = await Array.fromAsync(client.sshKeys.list()); > const key = keys.find(key => key.name === 'my-laptop'); > if (!image || !key) throw new Error('Select a compatible image and saved SSH key.'); > const result = await client.servers.create({ > hostname: 'web-1', datacenter, plan, image_id: image.id, > ssh_key_ids: [key.id], billing_period: 'monthly', > }); > const server = await client.servers.waitUntil(result, 'running', { timeoutMs: 600_000 }); > console.log(`ssh -i ~/.ssh/id_ed25519 ${server.login_user}@${server.ipv4}`); > ``` Run the printed [SSH command](/compute/virtual-machines/connect-ssh) using the private key matching the selected public key. Creation returns HTTP `201` with an order and a server that may still be provisioning or `null`. Waiters resolve acknowledged delayed creations and return the final server. Pre-orders can outlive the default 600-second deadline. Python async resource calls use the same arguments with `await`; `list()` remains an async iterator. Use `async with AsyncArct()` to close the client. Keep the original `result`: waiting does not overwrite its order or one-time password. Passwords are masked in normal representations and JSON. Deliberately unwrap a non-null password with Python `result.password.get_secret_value()` or TypeScript `result.password.getSecretValue()` only when needed. Omitted `ssh_key_ids` uses saved keys; an explicit empty array requests password access where supported. See [Creating Servers](/api-reference/creating-servers#login-password). ### Lifecycle and Completion | Operation | Python | TypeScript | | - | - | - | | Start / stop / restart | `servers.start(id)`, `stop(id)`, `restart(id)` | Same method names | | Reinstall | `servers.reinstall(id, image_id=...)` | `servers.reinstall(id, { image_id })` | | Wait for status | `servers.wait_until(result, "running")` | `servers.waitUntil(result, 'running')` | | Resize options / resize | `servers.resize_options(id)`, `resize(id, plan=...)` | `servers.resizeOptions(id)`, `resize(id, { plan })` | | Schedule deletion | `servers.delete(id, at_period_end=True)` | `servers.delete(id, { atPeriodEnd: true })` | | Cancel scheduled deletion | `servers.cancel_deletion(id)` | `servers.cancelDeletion(id)` | Start, stop, restart and reinstall return accepted HTTP `202` responses. Pass the **original action result** to a waiter: a bare server ID checks current status, while the original restart/reinstall result retains transition tracking. An initial stale `running` observation cannot prove those operations completed; a missed transition can time out as unverified. Waiters poll every 5 seconds by default. Python uses `timeout` in seconds; TypeScript uses `timeoutMs` in milliseconds. Timeouts expose `last_state` in Python or `lastState` in TypeScript. Cancellation stops waiting and does not cancel an accepted remote operation. Cancel an async Python task or pass an `AbortSignal` in the final TypeScript request/wait options. ### Resize Safely Stop the server and wait for `stopped` before resizing. `resize()` obtains an eligible quote and sends its exact `amount_due_today` as `expected_amount`. To retain an already reviewed quote, supply that amount explicitly. A `price_changed` conflict requires a new decision; it is never silently re-quoted. Python `servers.wait_resize(id, resize_result)` and TypeScript `servers.waitUntil(id, 'stopped', { plan: 'TARGET_PLAN' })` check resize completion. HTTP `200 applied` and `202 pending_payment` are distinct. A pending payment may need dashboard action. Start the server only after the requested plan is confirmed applied; resizing and waiting never start it automatically. Python monetary responses use `Decimal`. TypeScript monetary responses are JavaScript numbers, while automatic resize quoting preserves the original numeric text. Use a decimal string for an explicit TypeScript amount. Explicit Python `expected_amount=None` or TypeScript `expected_amount: null` opts out of price protection and accepts the current API price. ## Errors and Retry Safety Both SDKs export `APIError` and typed errors including `AuthenticationError`, `PaymentRequiredError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `ValidationError`, `RateLimitError`, `ChargeUnknownError`, `UncertainOperationError`, `WaitTimeoutError` and `OperationFailedError`. API errors expose `status`, `code` and redacted `details`; validation errors also expose `fields`. Unknown error codes fall back to their HTTP status class. See the [error reference](/api-reference/errors) for codes. * Reads and eligible creation failures have at most three total attempts; creation retries retain the identical body and hostname. Other uncertain mutations are not blindly repeated. * `429` honors `Retry-After` within the operation deadline. Local scheduling complements the server's [rate limits](/api-reference/rate-limits). * `details.order_intent_id` or `409 payment_pending` raises `ChargeUnknownError` without retrying. Keep support identifiers and verify billing before another purchase. * A lost response or a matching hostname cannot prove a successful order or recover its one-time password. `UncertainOperationError` requires reconciliation before repeating the action. Creation reconciliation compares placement without case sensitivity. Legacy `location="LON"` matches the location `lon`; a numbered alias such as `location="lon1"` matches `server.datacenter`. A missing or null datacenter cannot confirm that alias match. Candidate matches remain uncertain and never fabricate a successful order or trigger another create after a hostname conflict. ## Available Resources and Limits Shared resources are `account`, `servers`, `datacenters`, `locations`, `plans`, `images`, `invoices`, and Python `ssh_keys` / TypeScript `sshKeys`. New response fields and enum strings are accepted. `Server.datacenter` may be null until placement is known and absent from older responses; additive `Location.datacenters` and `Plan.datacenters` may also be absent. You can enable automatic backups **during server creation** with Python `enable_backups=True` or TypeScript `enable_backups: true`, where the selected plan supports them. There are no backup/snapshot management endpoints or SDK management methods. Use the [dashboard](/compute/virtual-machines/backups-snapshots) for backup and snapshot management. Token issuance/revocation, cards, password resets and VNC also remain dashboard operations. For API invoice payment with account credit, see [Account Credit](/api-reference/account-credit); the source Python SDK exposes `invoices.pay(id, payment_method="credit")`, while that method is not part of the shared TypeScript SDK surface. # Cancel a Scheduled Deletion Source: https://docs.arct.cloud/api-reference/servers/cancel-a-scheduled-deletion /api-reference/openapi.json post /servers/{server_id}/cancel-deletion Keeps a server scheduled with `DELETE /servers/{server_id}?at_period_end=true`; it renews as before and `cancel_at` becomes null. A server with nothing scheduled is returned unchanged. # Create a Server Source: https://docs.arct.cloud/api-reference/servers/create-a-server /api-reference/openapi.json post /servers Creates a server in `datacenter` and charges the first billing period to your default card, else your first saved card. A saved card is required unless `payment_method` is `credit`, which pays from account credit. Poll `GET /servers/{server_id}` until `status` is `running`. # Delete a Server Source: https://docs.arct.cloud/api-reference/servers/delete-a-server /api-reference/openapi.json delete /servers/{server_id} Deletes the server and wipes its disk. Can't be undone. Renewals stop and paid time isn't refunded; backups are deleted, snapshots kept. With `at_period_end=true`, nothing renews and the server is deleted when its paid period ends (`cancel_at`); undo it with `POST /servers/{server_id}/cancel-deletion`. # Get a Server Source: https://docs.arct.cloud/api-reference/servers/get-a-server /api-reference/openapi.json get /servers/{server_id} Returns one server, with `login_user` filled in. # List Resize Options Source: https://docs.arct.cloud/api-reference/servers/list-resize-options /api-reference/openapi.json get /servers/{server_id}/resize-options Returns the plans this server can resize to, with `amount_due_today` for each. # List Servers Source: https://docs.arct.cloud/api-reference/servers/list-servers /api-reference/openapi.json get /servers Returns your servers, newest first. # Reinstall a Server Source: https://docs.arct.cloud/api-reference/servers/reinstall-a-server /api-reference/openapi.json post /servers/{server_id}/reinstall Wipes the disk and installs `image_id`. The server must be running or stopped. Returns `202` while it reinstalls. # Resize a Server Source: https://docs.arct.cloud/api-reference/servers/resize-a-server /api-reference/openapi.json post /servers/{server_id}/resize Moves a stopped server to a bigger plan and charges the prorated difference to the server's billing card, else your default card, or to account credit with `payment_method: credit`. Returns `200` when paid, `202` while the payment processes. Start the server afterwards. # Restart a Server Source: https://docs.arct.cloud/api-reference/servers/restart-a-server /api-reference/openapi.json post /servers/{server_id}/restart Reboots a running server. Returns `202` while it restarts. # Start a Server Source: https://docs.arct.cloud/api-reference/servers/start-a-server /api-reference/openapi.json post /servers/{server_id}/start Starts a stopped server. Returns `202` while it boots. # Stop a Server Source: https://docs.arct.cloud/api-reference/servers/stop-a-server /api-reference/openapi.json post /servers/{server_id}/stop Powers off a running server. Returns `202` while it stops. # Update a Server Source: https://docs.arct.cloud/api-reference/servers/update-a-server /api-reference/openapi.json patch /servers/{server_id} Changes the hostname, delete protection or labels. Omitted fields keep their value. # Add an SSH Key Source: https://docs.arct.cloud/api-reference/ssh-keys/add-an-ssh-key /api-reference/openapi.json post /ssh-keys Saves a public key to install on new and reinstalled servers. # Delete an SSH Key Source: https://docs.arct.cloud/api-reference/ssh-keys/delete-an-ssh-key /api-reference/openapi.json delete /ssh-keys/{key_id} Deletes an SSH key. Servers that already have it keep it. # Get an SSH Key Source: https://docs.arct.cloud/api-reference/ssh-keys/get-an-ssh-key /api-reference/openapi.json get /ssh-keys/{key_id} Returns one SSH key. # List SSH Keys Source: https://docs.arct.cloud/api-reference/ssh-keys/list-ssh-keys /api-reference/openapi.json get /ssh-keys Returns your SSH keys, newest first. # Self-host Appwrite on a VPS Source: https://docs.arct.cloud/apps/appwrite Deploy Appwrite on an Ubuntu VPS with its official Docker installer, private account setup, HTTPS, backups, and safe migrations. Arct Cloud provides the unmanaged Linux VPS for this deployment. Appwrite is not preinstalled or managed by Arct Cloud. You are responsible for application configuration, data, functions, email delivery, security, backups, scaling, and updates. ## Choose a Plan Appwrite's [official installation requirements](https://appwrite.io/docs/advanced/self-hosting/installation) specify at least 2 CPU cores, 4 GB RAM, 2 GB swap, Docker Compose v2, and a current Docker Engine. | Profile | vCPU | RAM | NVMe storage | Guidance | | - | -: | -: | -: | - | | **cvm.micro** | 2 | 4 GB | 40 GB | Meets the official CPU and RAM minimum; suitable for evaluation and light development after adding 2 GB swap | | **cvm.small** | 4 | 8 GB | 75 GB | Practical Arct starting point with more headroom for workers, builds, functions, databases, and image downloads | Appwrite does not publish a universal disk minimum. It runs many containers and stores database records, uploads, function code, site builds, certificates, and logs. Monitor memory and disk usage, then increase resources or use an external storage backend as the workload grows. These are practical starting points, not performance guarantees. ## Before You Begin Prepare the following: * A fresh Ubuntu 24.04 server * A dedicated hostname such as `appwrite.example.com` * An `A` record pointing the hostname to the VPS's public IPv4 address * An email address for TLS certificate notifications * Encrypted off-server storage for configuration, database, and volume backups * An authenticated SMTP provider if users need verification or password recovery email This guide uses Appwrite's current stable `1.9.6` release and the installer's default MongoDB backend. Check the [Appwrite releases](https://github.com/appwrite/appwrite/releases) before installation and replace the version only after reviewing its release notes. ## Install Appwrite **1. Deploy and Connect** [Deploy an Ubuntu server](/compute/virtual-machines/deploy), then [connect over SSH](/compute/virtual-machines/connect-ssh). **2. Prepare DNS and the Firewall** Confirm the hostname resolves to this server: ```bash theme={null} getent ahostsv4 appwrite.example.com ``` Allow SSH before enabling UFW, then expose only the public web ports: ```bash theme={null} sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable sudo ufw status ``` Port `20080` is used only by Appwrite's installation wizard. The command below binds it to server loopback, so do not open it in UFW or an upstream firewall. **3. Install Docker Engine and Compose** Install Docker from Docker's official Ubuntu repository: ```bash theme={null} sudo apt update sudo apt install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null < [!WARNING] > > Run the swap creation commands only when `swapon --show` is empty and `/swapfile` does not already exist. **5. Start the Installer Privately** Create the parent directory, then run Appwrite's official installer with two deliberate safeguards: an exact image tag and a loopback-only wizard port. ```bash theme={null} sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/appwrite cd /opt sudo docker run -it --rm \ --publish 127.0.0.1:20080:20080 \ --volume /var/run/docker.sock:/var/run/docker.sock \ --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \ --entrypoint="install" \ appwrite/appwrite:1.9.6 ``` Leave this SSH session open while the installer waits for the web wizard. > [!WARNING] > > The installer controls Docker through `/var/run/docker.sock`, which is equivalent to root access on the host. Use only Appwrite's official image with a reviewed release tag. **6. Complete the Private Setup Wizard** From a second terminal on your local computer, open an SSH tunnel: ```bash theme={null} ssh -N -L 20080:127.0.0.1:20080 ubuntu@YOUR_SERVER_IP ``` Open `http://127.0.0.1:20080` and complete the wizard: 1. Enter `appwrite.example.com` as the hostname. 2. Keep MongoDB selected unless you have planned a MariaDB deployment and backup strategy. 3. Configure automatic HTTPS and its notification email. 4. Generate the application encryption key and save it outside the VPS. 5. Create the root console account with a unique password. 6. Review the settings, then start the installation. The setup wizard remains private for the entire first-account flow. Stop the tunnel with `Ctrl+C` only after the installer finishes and the root account exists. **7. Rotate Default Service Secrets** Appwrite's [database security guidance](https://appwrite.io/docs/advanced/self-hosting/configuration/databases) requires changing the database credentials before production. The `1.9.6` wizard sets the application encryption key, but its generated configuration retains known defaults for `_APP_DB_PASS`, `_APP_DB_ROOT_PASS`, and `_APP_EXECUTOR_SECRET`. Rotate all three immediately after setup and before creating projects or accepting production data. The following MongoDB-specific maintenance flow creates a root-only recovery set, transfers new values without printing them or placing them in host-side command arguments, changes the database credentials, atomically updates `.env`, and recreates every service with matching values: ```bash theme={null} ( set -euo pipefail cd /opt/appwrite sudo chmod 0600 .env pre_rotate_dir="/root/appwrite-pre-rotation-$(date -u +%Y%m%dT%H%M%SZ)" sudo install -d -m 0700 "$pre_rotate_dir" sudo cp -p .env docker-compose.yml "$pre_rotate_dir/" rotation_dir="$(sudo mktemp -d /root/appwrite-rotation.XXXXXX)" candidate_env="$(sudo mktemp /opt/appwrite/.env.rotate.XXXXXX)" rotation_finished=false report_rotation_state() { if [ "$rotation_finished" = false ]; then printf 'Rotation stopped. Keep recovery data in %s, %s, and %s if present.\n' \ "$pre_rotate_dir" "$rotation_dir" "$candidate_env" >&2 fi } trap report_rotation_state EXIT sudo sh -c ' set -eu umask 077 openssl rand -hex 32 >"$1/db-pass" openssl rand -hex 32 >"$1/db-root-pass" openssl rand -hex 32 >"$1/executor-secret" ' sh "$rotation_dir" sudo bash -s -- "$rotation_dir" "$candidate_env" <<'BUILD_ENV' set -euo pipefail secret_dir="$1" candidate="$2" env_file="/opt/appwrite/.env" db_pass="$(<"$secret_dir/db-pass")" db_root_pass="$(<"$secret_dir/db-root-pass")" executor_secret="$(<"$secret_dir/executor-secret")" seen_db=0 seen_root=0 seen_executor=0 while IFS= read -r line || [[ -n "$line" ]]; do case "$line" in _APP_DB_PASS=*) printf '_APP_DB_PASS="%s"\n' "$db_pass" ((seen_db += 1)) ;; _APP_DB_ROOT_PASS=*) printf '_APP_DB_ROOT_PASS="%s"\n' "$db_root_pass" ((seen_root += 1)) ;; _APP_EXECUTOR_SECRET=*) printf '_APP_EXECUTOR_SECRET="%s"\n' "$executor_secret" ((seen_executor += 1)) ;; *) printf '%s\n' "$line" ;; esac done <"$env_file" >"$candidate" if (( seen_db != 1 || seen_root != 1 || seen_executor != 1 )); then echo 'Expected each Appwrite secret exactly once; rotation was not started.' >&2 exit 1 fi chown root:root "$candidate" chmod 0600 "$candidate" BUILD_ENV sudo docker compose stop sudo docker compose up -d --wait mongodb sudo docker compose exec -T mongodb sh -c \ 'exec mongodump --username=root --password="$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase=admin --archive' \ | sudo tee "$pre_rotate_dir/mongodb.archive" >/dev/null sudo docker compose cp \ "$rotation_dir/db-pass" mongodb:/tmp/appwrite-new-db-pass sudo docker compose cp \ "$rotation_dir/db-root-pass" mongodb:/tmp/appwrite-new-db-root-pass sudo docker compose exec -T mongodb bash -se <<'ROTATE_MONGO' set -euo pipefail export NEW_DB_PASS="$(cat /tmp/appwrite-new-db-pass)" export NEW_ROOT_PASS="$(cat /tmp/appwrite-new-db-root-pass)" mongosh --quiet \ --username "$MONGO_INITDB_ROOT_USERNAME" \ --password "$MONGO_INITDB_ROOT_PASSWORD" \ --authenticationDatabase admin \ --eval ' const admin = db.getSiblingDB("admin"); admin.changeUserPassword( process.env.MONGO_INITDB_USERNAME, process.env.NEW_DB_PASS ); admin.changeUserPassword( process.env.MONGO_INITDB_ROOT_USERNAME, process.env.NEW_ROOT_PASS ); ' rm -f /tmp/appwrite-new-db-pass /tmp/appwrite-new-db-root-pass ROTATE_MONGO sudo mv -- "$candidate_env" /opt/appwrite/.env sudo docker compose up -d --force-recreate --wait sudo docker compose exec -T mongodb bash -se <<'VERIFY_MONGO' mongosh --quiet \ --username "$MONGO_INITDB_USERNAME" \ --password "$MONGO_INITDB_PASSWORD" \ --authenticationDatabase admin \ --eval 'if (db.getSiblingDB(process.env.MONGO_INITDB_DATABASE).runCommand({ ping: 1 }).ok !== 1) { quit(1); }' \ >/dev/null VERIFY_MONGO sudo docker compose exec -T appwrite sh -ec ' printf "header = \"Authorization: Bearer %s\"\n" \ "$_APP_EXECUTOR_SECRET" \ | curl --config - --fail --silent --show-error \ "${_APP_EXECUTOR_HOST}/health" >/dev/null ' sudo docker exec appwrite doctor sudo docker compose ps sudo bash <<'CHECK_SECRETS' set -euo pipefail declare -A secret=() while IFS='=' read -r key raw; do case "$key" in _APP_OPENSSL_KEY_V1|_APP_DB_PASS|_APP_DB_ROOT_PASS|_APP_EXECUTOR_SECRET) raw="${raw#\"}" raw="${raw%\"}" secret["$key"]="$raw" ;; esac done &2 bad=1 fi case "$current" in your-secret-key|password|rootsecretpassword) printf '%s still uses an Appwrite default.\n' "$key" >&2 bad=1 ;; esac done if [[ "${secret[_APP_DB_PASS]-}" == "${secret[_APP_DB_ROOT_PASS]-}" || "${secret[_APP_DB_PASS]-}" == "${secret[_APP_EXECUTOR_SECRET]-}" || "${secret[_APP_DB_ROOT_PASS]-}" == "${secret[_APP_EXECUTOR_SECRET]-}" ]]; then echo 'Appwrite secrets must be distinct.' >&2 bad=1 fi (( bad == 0 )) echo 'Required Appwrite secrets are non-default, sufficiently long, and distinct.' CHECK_SECRETS sudo rm -f -- \ "$rotation_dir/db-pass" \ "$rotation_dir/db-root-pass" \ "$rotation_dir/executor-secret" sudo rmdir -- "$rotation_dir" rotation_finished=true trap - EXIT printf 'Pre-rotation recovery set: %s\n' "$pre_rotate_dir" ) ``` > [!WARNING] > > This sequence is only for the MongoDB deployment in this guide. If it stops after changing MongoDB, do not restart the full stack or delete `/root/appwrite-rotation.*` or `/opt/appwrite/.env.rotate.*`. Keep the root-only recovery files, determine which credential changes completed, then finish installing the candidate `.env` or restore on a fresh instance. Copy `.env` and the pre-rotation recovery set to encrypted off-server storage. Never regenerate `_APP_OPENSSL_KEY_V1` on an existing instance: Appwrite uses it to protect passwords, OAuth secrets, API keys, and other sensitive values. **8. Verify the Deployment** Confirm the containers are healthy, then make the first HTTPS request. Appwrite can initially present a self-signed certificate; the first request triggers certificate issuance. Use `--insecure` only for that initial probe, wait for the certificate to be issued in the logs, and require the final check to pass normal TLS validation: ```bash theme={null} cd /opt/appwrite sudo docker compose ps curl --insecure --head https://appwrite.example.com sudo docker compose logs --tail=50 appwrite traefik mongodb redis curl --fail --show-error --head https://appwrite.example.com sudo docker exec appwrite doctor ``` Sign in with the root account created in the private wizard, create a test project, and verify that its API endpoint uses `https://appwrite.example.com/v1`. ## Production Security and Operations Only ports `22`, `80`, and `443` should normally be public. Port `20080` is temporary and loopback-only. Database, Redis, worker, executor, and Docker API ports must remain private. Before storing production data: * Keep `_APP_OPENSSL_KEY_V1` unchanged and backed up separately from the database * Require the default-secret rotation and non-printing validation above to pass * Force HTTPS and confirm no application SDK uses the plain HTTP endpoint * Keep console registration restricted to the root user and invite additional developers * Use Appwrite's console IP or email allowlists when the dashboard needs tighter access * Keep Appwrite's abuse protection and rate limits enabled * Configure authenticated SMTP and test verification and password-reset delivery * Use least-privilege API keys and review function permissions and runtime limits * Monitor CPU, RAM, swap, disk, container health, and log growth Docker-published ports can bypass ordinary UFW forwarding rules. The wizard port is safe here because it is explicitly bound to `127.0.0.1`; review every future Compose `ports` change before applying it. ## Back Up and Restore Self-hosted Appwrite does not provide automatic backups. A complete recovery set includes the database, Appwrite storage volumes, `.env`, `docker-compose.yml`, the encryption key, and the exact image versions. For the MongoDB deployment used in this guide, the following maintenance-window example records the configuration, stops Appwrite, creates an official logical database dump, and archives every non-database Compose-managed volume: ```bash theme={null} ( set -euo pipefail cd /opt/appwrite stamp="$(date -u +%Y%m%dT%H%M%SZ)" backup_dir="/opt/appwrite-backups/${stamp}" sudo install -d -m 0700 -o "$USER" -g "$USER" "$backup_dir" sudo cp -p .env docker-compose.yml "$backup_dir/" sudo chown "$USER:$USER" "$backup_dir/.env" \ "$backup_dir/docker-compose.yml" sudo docker compose config --images >"$backup_dir/images.txt" sudo docker compose config --volumes >"$backup_dir/volumes.txt" mapfile -t appwrite_volumes < <( sudo docker volume ls -q \ --filter label=com.docker.compose.project=appwrite ) test "${#appwrite_volumes[@]}" -gt 0 sudo docker pull ubuntu:24.04 stopped=false restart_appwrite() { if [ "$stopped" = true ]; then sudo docker compose up -d || true fi } trap restart_appwrite EXIT trap 'exit 130' INT trap 'exit 143' TERM stopped=true sudo docker compose down sudo docker compose up -d --wait mongodb sudo docker compose exec -T mongodb sh -c \ 'exec mongodump --username=root --password="$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase=admin --archive' \ >"$backup_dir/mongodb.archive" sudo docker compose stop mongodb for volume in "${appwrite_volumes[@]}"; do case "$volume" in *mongodb*|*mariadb*|*postgresql*) continue ;; esac sudo docker run --rm \ --volume "${volume}:/data:ro" \ --volume "${backup_dir}:/backup" \ ubuntu:24.04 \ tar -czf "/backup/${volume}.tar.gz" -C /data . done sudo docker compose up -d stopped=false trap - EXIT INT TERM sudo chown -R "$USER:$USER" "$backup_dir" chmod -R go-rwx "$backup_dir" printf 'Appwrite backup ready: %s\n' "$backup_dir" ) ``` Copy the entire timestamped directory to encrypted storage outside the VPS and test it on a separate server. If you select MariaDB in the installer, use Appwrite's documented `mysqldump` procedure instead of the MongoDB command. Restore only into a fresh installation running the matching Appwrite and database versions. For this MongoDB path, restore `mongodb.archive` into the fresh database, then restore the non-database storage archives with the saved configuration and encryption key. Do not also restore a raw MongoDB data volume: logical database restore and raw database-volume restore are alternative recovery methods. Never restore over a live database or delete the current volumes until the replacement instance has passed login, API, upload, function, and project checks. ## Update and Migrate Safely Appwrite updates can change both its Compose project and data schema. Before every update: 1. Create and verify a complete off-server backup. 2. Read every intervening [release note](https://github.com/appwrite/appwrite/releases). 3. Record the current image tags and keep the existing VPS available. 4. Test the same upgrade path on a replacement instance. Run the official upgrade tool from the parent directory, replacing the example variable with an exact release tag: ```bash theme={null} cd /opt APPWRITE_VERSION=REPLACE_WITH_EXACT_RELEASE_TAG sudo docker run -it --rm \ --publish 127.0.0.1:20080:20080 \ --volume /var/run/docker.sock:/var/run/docker.sock \ --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \ --entrypoint="upgrade" \ "appwrite/appwrite:${APPWRITE_VERSION}" ``` Leave that command running while it waits for the private upgrade wizard. From a second terminal on your local computer, recreate the SSH tunnel: ```bash theme={null} ssh -N -L 20080:127.0.0.1:20080 ubuntu@YOUR_SERVER_IP ``` Open `http://127.0.0.1:20080`, review the detected deployment and exact target release, then complete the upgrade wizard. Close the tunnel only after the upgrade command finishes. Patch releases do not always require a data migration. Run the migration command only when the release notes require it: ```bash theme={null} cd /opt/appwrite sudo docker compose exec appwrite migrate sudo docker compose ps sudo docker compose logs --tail=100 appwrite ``` When crossing minor versions, Appwrite requires upgrading through each minor version's latest patch. Do not start an older Appwrite image against data that a newer migration has changed. If an update fails, restore the complete pre-update recovery set on a fresh matching-version server instead of attempting an in-place downgrade. ## Troubleshooting > [accordion] The installation wizard does not open > > Keep the installer terminal running, confirm `sudo ss -lntp | grep ':20080'` shows a loopback listener, and reconnect the SSH tunnel. Do not change the mapping to `0.0.0.0:20080` as a shortcut. > [accordion] HTTPS certificate issuance fails > > Confirm the `A` record points to this VPS, remove an incorrect `AAAA` record, and verify ports `80` and `443` are reachable. Review the Traefik and Appwrite logs for ACME or hostname errors. > [accordion] Containers restart or the server becomes unresponsive > > Run `free -h`, `swapon --show`, `df -h`, and `sudo docker stats`. Appwrite's many workers and build images can exceed the minimum profile; add memory or storage before increasing worker concurrency. > [accordion] Users do not receive verification or reset email > > Configure an authenticated SMTP provider, normally on submission port `587`, then test delivery and inspect the worker logs. Do not rely on unauthenticated local mail delivery. > [accordion] An update or migration fails > > Stop retrying against production data. Inspect the first migration error and the exact release notes, then recover on a separate server from the pre-update database, volumes, configuration, and encryption key. ## Official Resources > [card] [Appwrite Installation](https://appwrite.io/docs/advanced/self-hosting/installation) > > Official requirements, Docker installer, setup wizard, and manual Compose files. > [card] [Production Checklist](https://appwrite.io/docs/advanced/self-hosting/production) > > Security, scaling, email, monitoring, backups, and update guidance. > [card] [Appwrite on GitHub](https://github.com/appwrite/appwrite) > > Source code, releases, security policy, and issue tracker. > [!NOTE] > > Appwrite is developed by Appwrite. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by Appwrite. # Self-Host Coolify on a VPS Source: https://docs.arct.cloud/apps/coolify Install Coolify on an Arct Cloud Linux VPS, secure its dashboard with HTTPS, and configure backups and safe updates. Arct Cloud provides an unmanaged Linux VPS. Coolify is not preinstalled or managed by Arct Cloud; you are responsible for the Coolify control plane, deployed workloads, security, backups, and updates. This guide installs self-hosted Coolify on a fresh Ubuntu 24.04 server using Coolify's recommended automated installer. Ubuntu 24.04 LTS is supported by that installer. ## Requirements | Basis | CPU | RAM | Storage | | - | -: | -: | -: | | **Official Coolify minimum** | 2 cores | 2 GB | 10 GB free | | **Practical Arct recommendation** | 2 vCPUs | 4 GB | 40 GB NVMe (`cvm.micro`) | The official minimum runs the control plane. Builds, Docker images, databases, application volumes, and backups need additional resources. For several applications or local image builds, start with 4 vCPUs and 8 GB RAM (`cvm.small`) and monitor disk usage. > [!WARNING] > > Install Coolify on a fresh server when possible. Ports, Docker configuration, and existing reverse proxies can conflict with the automated installer. ## Install Coolify **1. Deploy Ubuntu 24.04** [Deploy a server](/compute/virtual-machines/deploy), select a plan based on the control plane and workloads you will run, and choose Ubuntu 24.04. **2. Connect over SSH** Find the server IP address in the Arct Cloud console, then connect: ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP ``` See [Connect via SSH](/compute/virtual-machines/connect-ssh) for key and username help. **3. Prepare DNS and a protected bootstrap path** Create an `A` record such as `coolify.example.com` that points to the server's public IPv4 address. Add an `AAAA` record only when IPv6 is configured and reachable. Coolify binds these TCP ports during setup: | Port | Purpose | | -: | - | | `22` | SSH and Coolify's connection to the server | | `80` | HTTP traffic and certificate issuance | | `443` | HTTPS traffic | | `8000` | Direct dashboard access during setup; keep private | | `6001` | Real-time dashboard updates during direct-IP setup; keep private | | `6002` | Web terminal during direct-IP setup; keep private | Confirm the ports are not already occupied: ```bash theme={null} sudo ss -lntp getent ahostsv4 coolify.example.com ``` Before running the installer, attach a network-level firewall or ACL in front of the VPS with this inbound policy: | Ports | Source during bootstrap | | - | - | | `22/tcp` | Your current public admin IP only | | `80/tcp`, `443/tcp` | Any, for the dashboard domain and certificate issuance | | `8000/tcp`, `6001/tcp`, `6002/tcp` | Deny from the public internet | | All other inbound ports | Deny unless a deployed workload explicitly requires one | Keep the current SSH session open while changing firewall rules. Attach and verify this policy **before** installation. Coolify's [official firewall guide](https://coolify.io/docs/knowledge-base/server/firewall) explains that Docker-published ports bypass plain UFW rules and recommends a provider firewall. If no upstream firewall is available, configure the guide's Docker-aware `ufw-docker` alternative before proceeding; an ordinary UFW deny rule is not sufficient. **4. Run the official installer** Coolify recommends its automated installation script. Run it with root privileges from the fresh server: ```bash theme={null} curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash ``` The installer adds required packages, installs Docker Engine when needed, creates `/data/coolify`, generates secrets and SSH keys, and starts the control plane. Do not install Docker through Snap. **5. Claim the administrator account** From your local computer, open an SSH tunnel for the direct-IP setup services and leave it running: ```bash theme={null} ssh -L 8000:127.0.0.1:8000 \ -L 6001:127.0.0.1:6001 \ -L 6002:127.0.0.1:6002 \ ubuntu@YOUR_SERVER_IP ``` Confirm that `http://YOUR_SERVER_IP:8000` is unreachable without the tunnel, then open `http://127.0.0.1:8000` through the tunnel. Create the first administrator with a unique password and enable two-factor authentication before adding servers or secrets. > [!WARNING] > > Anyone who reaches the registration page first can become the Coolify administrator and gain root-level control of the server. Do not proceed if port `8000` is reachable directly from a non-allowlisted network. **6. Configure the dashboard domain and HTTPS** Wait until `coolify.example.com` resolves to this VPS. In Coolify, open **Settings > Configuration > General**, set **URL** to the complete address `https://coolify.example.com`, and save. Coolify's integrated proxy requests and renews the TLS certificate. Confirm the dashboard, real-time updates, and web terminal all work through the HTTPS domain before restricting the setup ports. **7. Protect secrets and remove direct public access** Back up the generated environment file immediately: ```bash theme={null} sudo install -d -m 700 /data/coolify-backup sudo cp --preserve=mode,timestamps \ /data/coolify/source/.env /data/coolify-backup/coolify.env ``` Copy this backup to encrypted storage outside the VPS. It includes `APP_KEY`, which Coolify needs to decrypt credentials during a restore. After the HTTPS dashboard, real-time connection, and web terminal are verified, keep ports `8000`, `6001`, and `6002` denied at the network firewall and close the SSH tunnel. Keep `22`, `80`, and `443` available as required. Recheck the policy whenever you add direct port mappings to a workload. **8. Verify the installation** Check the control-plane containers and public endpoint: ```bash theme={null} sudo docker ps --filter name=coolify \ --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' curl -I https://coolify.example.com sudo docker logs --tail 50 coolify ``` In the dashboard, open **Servers > localhost**, validate the server, deploy a small test resource, and confirm it is reachable through HTTPS. ## Persistent Data and Security Coolify stores its control-plane configuration under `/data/coolify`, including its environment file, SSH keys, proxy configuration, application definitions, and local backups. Do not edit the base Compose files in `/data/coolify/source`; updates replace them. Use `docker-compose.custom.yml` for supported overrides. | Data | What to protect | | - | - | | Coolify internal database | Projects, server records, configuration, and encrypted credentials | | `/data/coolify/source/.env` | The `APP_KEY` and generated database or service secrets | | `/data/coolify/ssh/keys/` | Private keys used to manage localhost and remote servers | | Application databases and volumes | Workload data; not included in a Coolify instance database backup | Use a unique administrator password and enable two-factor authentication. Keep SSH key-only where possible, restrict administrative access, and do not expose databases or application container ports unless a client explicitly needs them. Applications routed through the Coolify proxy normally need only ports `80` and `443`. > [!WARNING] > > Coolify can control Docker and connect to servers over SSH. A compromised administrator account can compromise every managed workload and secret. Treat the dashboard as privileged infrastructure. ## Back Up and Restore Configure two separate backup layers: 1. In **Settings > Backup**, add an S3-compatible destination, schedule a Coolify instance database backup, run it once manually, and verify the object exists in remote storage. 2. Save `/data/coolify/source/.env`, especially `APP_KEY`, and `/data/coolify/ssh/keys/` in encrypted off-server storage. 3. Configure scheduled backups for each application database and persistent volume. A Coolify instance backup does not include workload databases, application volumes, or arbitrary files on managed servers. 4. Record the Coolify version whenever you take a recovery checkpoint. To restore, install the matching Coolify version on the target server, restore the saved `APP_KEY`, load the instance `.dmp` backup into Coolify's database using the official restore procedure, restore the SSH keys, and then restore every application database and volume independently. Test this process on a replacement server before relying on it for production recovery. > [!NOTE] > > Keep at least one backup outside the Coolify server. A local backup cannot help if the VPS, filesystem, or account becomes unavailable. ## Update and Roll Back Safely Before changing the Coolify version: 1. Create and verify an instance backup plus workload backups. 2. Copy `.env` and SSH keys off-server. 3. Review the [Coolify releases](https://github.com/coollabsio/coolify/releases) and wait for active deployments to finish. 4. Record the current version shown in the dashboard. Update during a maintenance window from **Settings > Configuration > Updates**, or run the official installer over SSH: ```bash theme={null} curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash ``` After the update, verify the displayed version, localhost validation, proxy, web terminal, and representative application/database resources. Update logs are written under `/data/coolify/source/` as `upgrade-*.log`. To return to a known release, disable automatic updates and run the installer with the exact target version from the official releases page: ```bash theme={null} COOLIFY_VERSION=REPLACE_WITH_RELEASE_TAG curl -fsSL https://cdn.coollabs.io/coolify/install.sh \ | sudo bash -s "$COOLIFY_VERSION" ``` An older control-plane image may not understand database migrations made by a newer release. If the downgrade fails, stop and restore the pre-update instance database with its matching `APP_KEY` instead of repeatedly downgrading. Coolify control-plane rollback does not roll back deployed applications or their data. ## Troubleshooting > [accordion] The installer finishes but port 8000 does not open > > Port `8000` should remain blocked publicly. Connect through the SSH tunnel, then check `sudo ss -lntp | grep ':8000'`, `sudo docker ps --filter name=coolify`, and the newest `/data/coolify/source/upgrade-*.log`. Another service occupying port `8000` can prevent a correct start. > [accordion] The domain works over HTTP but not HTTPS > > Confirm the `A` record points to this server and ports `80` and `443` are publicly reachable. Remove an incorrect `AAAA` record, then inspect the Coolify proxy logs for ACME errors. > [accordion] The dashboard loads but real-time updates or web terminal fail > > Before domain setup, direct-IP access also needs ports `6001` and `6002`. After domain setup, confirm the instance URL uses `https://` and that the proxy routes the dashboard, real-time service, and terminal before closing those ports. > [accordion] Applications fail during builds or the server freezes > > Check `free -h`, `df -h`, and `sudo docker system df`. Builds can exceed the control-plane minimum. Add RAM/storage, use a dedicated build server, and configure Coolify's automated Docker cleanup rather than deleting active volumes. > [accordion] A restored instance reports an Invalid MAC or encryption error > > The restored database and active `APP_KEY` do not match. Restore the exact key saved with that backup; generating a replacement cannot decrypt existing values. ## Official Resources > [card] [Coolify Installation](https://next.coolify.io/docs/start-with-self-hosted) > > Official requirements, supported systems, and automated installation. > [card] [Coolify on GitHub](https://github.com/coollabsio/coolify) > > Source code, installer, security policy, and issue tracker. > [card] [Coolify Releases](https://github.com/coollabsio/coolify/releases) > > Stable releases, fixes, and upgrade notes. > [!NOTE] > > Coolify is developed by Coollabs. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by Coollabs. # Self-Host Dokploy on a VPS Source: https://docs.arct.cloud/apps/dokploy Install Dokploy on an Arct Cloud Linux VPS with a secure HTTPS panel, persistent data, backups, and safe updates. Arct Cloud provides an unmanaged Linux VPS. Dokploy is not preinstalled or managed by Arct Cloud; you are responsible for the Dokploy control plane, Docker Swarm, deployed workloads, security, backups, and updates. This guide installs Dokploy on a fresh Ubuntu 24.04 server using Dokploy's official stable installation script. Ubuntu 24.04 LTS is listed as a tested distribution by Dokploy. ## Requirements | Basis | CPU | RAM | Storage | | - | -: | -: | -: | | **Official Dokploy minimum** | No numeric minimum published | 2 GB | 30 GB | | **Practical Arct recommendation** | 2 vCPUs | 4 GB | 40 GB NVMe (`cvm.micro`) | The official minimum accounts for Docker build overhead. Use more CPU, RAM, and storage for concurrent builds, several databases, large images, or high-traffic services. A 4-vCPU, 8-GB RAM server (`cvm.small`) is a more practical starting point for multiple production workloads. > [!WARNING] > > Use a fresh server when possible. Dokploy requires ports `80`, `443`, and `3000` to be free during installation and initializes Docker Swarm. ## Install Dokploy **1. Deploy Ubuntu 24.04** [Deploy a server](/compute/virtual-machines/deploy), select a plan for the control plane plus your applications, and choose Ubuntu 24.04. **2. Connect over SSH** Find the server IP address in the Arct Cloud console, then connect: ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP ``` See [Connect via SSH](/compute/virtual-machines/connect-ssh) for key and username help. **3. Prepare DNS and a protected bootstrap path** Create an `A` record such as `dokploy.example.com` that points to the server's public IPv4 address. Add an `AAAA` record only when IPv6 is configured and reachable. Dokploy requires these TCP ports to be available: | Port | Purpose | | -: | - | | `22` | SSH administration | | `80` | Traefik HTTP traffic and certificate issuance | | `443` | Traefik HTTPS traffic | | `3000` | Direct Dokploy panel access during setup; keep private | Check listeners and DNS before installing: ```bash theme={null} sudo ss -lntp getent ahostsv4 dokploy.example.com ``` The installer fails if another process already uses `80`, `443`, or `3000`. A port can be free for Dokploy to bind without being reachable from the internet. Before running the installer, attach a network-level firewall or ACL in front of the VPS with this inbound policy: | Ports | Source during bootstrap | | - | - | | `22/tcp` | Your current public admin IP only | | `80/tcp`, `443/tcp` | Any, for Traefik and certificate issuance | | `3000/tcp` | Deny from the public internet | | All other inbound ports | Deny unless a deployed workload explicitly requires one | Attach and verify the policy before installation. Docker and Swarm published ports can bypass ordinary UFW rules. If no upstream firewall is available, preinstall Docker and establish a `DOCKER-USER` policy by following Docker's [official packet-filtering guidance](https://docs.docker.com/engine/network/packet-filtering-firewalls/) before running the Dokploy installer; a plain UFW deny rule is not a safe bootstrap boundary. **4. Run the official stable installer** Become root and run Dokploy's documented installation command. The installer selects the latest stable release and installs Docker when it is absent. ```bash theme={null} sudo -i curl -sSL https://dokploy.com/install.sh | sh exit ``` Do not select the `canary` channel for a production control plane. If the script cannot detect the correct address on a multi-interface server, use Dokploy's documented `ADVERTISE_ADDR` option rather than reinitializing Swarm manually. **5. Create the administrator** From your local computer, create an SSH tunnel and leave it running: ```bash theme={null} ssh -L 3000:127.0.0.1:3000 ubuntu@YOUR_SERVER_IP ``` Confirm that `http://YOUR_SERVER_IP:3000` is unreachable without the tunnel, then open `http://127.0.0.1:3000` through the tunnel. Complete the administrator setup with a long, unique password and enable two-factor authentication from the account settings. Do not continue if port `3000` is reachable directly from a non-allowlisted network. Do not connect Git providers, registries, or production secrets until the panel is protected with HTTPS. **6. Configure the panel domain and HTTPS** Confirm `dokploy.example.com` resolves to this VPS. In the Dokploy panel's domain settings, create the panel domain with: | Field | Value | | - | - | | Host | `dokploy.example.com` | | Path | `/` | | Container port | `3000` | | HTTPS | On | | Certificate | Let's Encrypt | Wait for Traefik to issue the certificate, then verify login at `https://dokploy.example.com`. **7. Remove direct access to port 3000** Only after the HTTPS panel works, remove the public IP-and-port publication recommended by Dokploy: ```bash theme={null} sudo docker service update \ --publish-rm "published=3000,target=3000,mode=host" dokploy ``` Keep ports `80` and `443` public for Traefik and certificate renewal, keep the upstream firewall deny for port `3000`, and close the SSH tunnel. Restrict SSH to trusted addresses where possible. **8. Verify the installation** Confirm the Swarm services, proxy, and public endpoint are healthy: ```bash theme={null} sudo docker service ls sudo docker service ps dokploy --no-trunc sudo docker ps --filter name=dokploy-traefik \ --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' curl -I https://dokploy.example.com ``` Deploy a small test application, attach a test domain, and confirm HTTPS routing and logs work before adding production data. ## Persistent Data, Secrets, and Firewall Safety Dokploy's control-plane state includes its internal PostgreSQL database and files under `/etc/dokploy`. The official control-plane backup combines both. Do not remove the Dokploy Docker volumes, Docker secrets, Swarm state, or `/etc/dokploy` during routine maintenance. | Data | Backup method | | - | - | | Dokploy database and `/etc/dokploy` | **Web Server > Backups** to an S3-compatible destination | | Application databases | Each database's **Backup** tab and tested S3 restore | | Docker named volumes | Dokploy **Volume Backups** to S3; stop the writing container for the safest consistent copy | | Bind mounts and host files | Separate filesystem backup; Dokploy volume backups cover named volumes, not bind mounts | | Registry, Git, and application secrets | Included in control-plane state; protect backups and use least-privilege tokens | Prefer Dokploy's domain routing through Traefik instead of direct **Advanced > Ports** mappings. A domain's container-port field routes internally and does not publish that port on the host. When a database or service must be externally reachable, allow only the exact source IPs or place it behind a VPN. > [!WARNING] > > Dokploy manages Docker Swarm and can deploy privileged workloads. A compromised administrator or Git/registry credential can affect every service on the server. Limit panel access, rotate tokens, and grant repository access only where needed. ## Back Up and Restore Configure and test all three recovery layers: 1. Add an S3-compatible destination in Dokploy. 2. Open **Web Server > Backups**, create a scheduled control-plane backup, run one immediately, and confirm the `.zip` object exists remotely. It contains the Dokploy PostgreSQL database and `/etc/dokploy`. 3. Schedule backups for every managed database and test each backup job. 4. Configure volume backups for named volumes. Enable **Turn off Container** when the application writes to the volume and consistency matters. 5. Keep a record of the running Dokploy release with each recovery checkpoint. To restore the control plane, open **Web Server > Backups > Restore Backup**, select the S3 destination and backup, review the destructive restore summary, and start the restore. Dokploy replaces the current `/etc/dokploy` content and internal database; you may need to sign in again and restart Traefik afterward. If the server IP changed, update it in **Web Server > Server**, update DNS, and reconfigure IP-based Git provider callbacks. Restore application databases and volumes separately because they are not part of the control-plane archive. > [!NOTE] > > Test recovery on a separate VPS. A backup is not verified until you can sign in, see projects, deploy, resolve domains, and restore representative database and volume data. ## Update and Roll Back Safely Before an update: 1. Run and verify a control-plane backup plus all application database and volume backups. 2. Review the [Dokploy releases](https://github.com/Dokploy/dokploy/releases) for breaking changes. 3. Let active builds and deployments finish. 4. Record the current service image: ```bash theme={null} sudo docker service inspect dokploy \ --format '{{.Spec.TaskTemplate.ContainerSpec.Image}}' ``` Update to the latest stable release with Dokploy's official command: ```bash theme={null} sudo -i curl -sSL https://dokploy.com/install.sh | sh -s update exit ``` Verify panel login, Swarm services, Traefik, domains, and a representative deployment before cleaning up old images. Dokploy intentionally does not update Traefik automatically; do not replace Traefik independently without checking Dokploy compatibility and Traefik breaking changes. The installer can target an exact official Dokploy version when recovery requires it: ```bash theme={null} sudo -i export DOKPLOY_VERSION=REPLACE_WITH_PREVIOUS_RELEASE curl -sSL https://dokploy.com/install.sh | sh -s update exit ``` Use a version copied from Dokploy's releases page. If an older control-plane image is incompatible with database changes, restore the full pre-update control-plane backup rather than repeatedly changing versions. Application rollback is separate: configure health checks for Swarm automatic rollback or a registry for deployment-level image rollback. ## Troubleshooting > [accordion] The installer reports that a required port is already in use > > Run `sudo ss -lntp | grep -E ':(80|443|3000) '` and stop or move the conflicting service. Dokploy's Traefik must own ports `80` and `443`; do not install a second host reverse proxy on those ports. > [accordion] The panel domain returns 404 or has no certificate > > Confirm DNS points to this VPS before creating the domain, ports `80` and `443` are reachable, HTTPS is enabled, and Let's Encrypt is selected. Check the Dokploy Traefik logs for routing or ACME errors. > [accordion] The panel became unreachable after port 3000 was removed > > Use SSH or the Arct Cloud VNC console to restore the port publication while keeping the upstream firewall deny in place: > > ```bash theme={null} > sudo docker service update \ > --publish-add "published=3000,target=3000,mode=host" dokploy > ``` > > Access it through the SSH tunnel, fix and verify the HTTPS route, then remove the publication again. Never reopen the bootstrap installer port to the public internet. > [accordion] A Dokploy service is stuck or repeatedly rejected > > Inspect `sudo docker service ps SERVICE_NAME --no-trunc`, `sudo docker service logs SERVICE_NAME --tail 100`, and `sudo docker node ls`. Address the first Swarm error rather than deleting volumes or reinitializing the cluster. > [accordion] Builds freeze the server or fail unexpectedly > > Check `free -h`, `df -h`, `sudo docker system df`, and service logs. Increase RAM or storage, reduce concurrent builds, or move builds off the control-plane host. Never prune named volumes as a generic disk-space fix. ## Official Resources > [card] [Dokploy Installation](https://docs.dokploy.com/docs/core/installation) > > Official requirements, supported distributions, ports, and installer. > [card] [Dokploy on GitHub](https://github.com/Dokploy/dokploy) > > Source code, security policy, and issue tracker. > [card] [Dokploy Releases](https://github.com/Dokploy/dokploy/releases) > > Stable releases, fixes, and upgrade notes. > [!NOTE] > > Dokploy is developed by the Dokploy project. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by Dokploy. # Self-host Gitea on a VPS Source: https://docs.arct.cloud/apps/gitea Deploy Gitea on an Ubuntu VPS with the official rootless container, HTTPS, Git over SSH, backups, and safe upgrades. Arct Cloud provides the unmanaged Linux VPS for this deployment. Gitea is not preinstalled or managed by Arct Cloud. You are responsible for repositories, user access, secrets, backups, integrations, and updates. ## Choose a Plan Gitea's [official requirements guidance](https://docs.gitea.com/) states that 2 CPU cores and 1 GB RAM are typically sufficient for small teams and projects. Repository size, Git LFS, Actions, packages, indexing, and concurrent users can increase requirements. | Profile | vCPU | RAM | NVMe storage | Guidance | | - | -: | -: | -: | - | | **Official small-team baseline** | 2 | 1 GB | Workload-dependent | Typical upstream guidance, not a hard maximum | | **Practical Arct starting point** | 2 | 4 GB | 40 GB or more | Small teams with operational and indexing headroom | Store Actions runners on separate, isolated machines. Runner workloads can execute repository-controlled code and should not share the Gitea application VPS. ## Before You Begin Prepare the following: * A fresh Ubuntu 24.04 server * A dedicated hostname such as `git.example.com` * An `A` record pointing the hostname to the server's public IPv4 address * Docker Engine with the Docker Compose plugin, installed from Docker's [official Ubuntu repository](https://docs.docker.com/engine/install/ubuntu/) * A decision about Git transport: HTTPS only, or HTTPS plus SSH on port `2222` The guide uses Gitea's official rootless image and SQLite, which upstream supports for a simple small-team deployment. The rootless and standard images use different volume layouts and must not be swapped after installation. ## Install Gitea **1. Deploy and Connect** [Deploy an Ubuntu server](/compute/virtual-machines/deploy), then [connect over SSH](/compute/virtual-machines/connect-ssh). **2. Create Persistent Directories** ```bash theme={null} sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/gitea cd /opt/gitea mkdir data config sudo chown -R 1000:1000 data config ``` UID and GID `1000` are the rootless image defaults. Incorrect ownership prevents Gitea from writing its configuration or repositories. **3. Create the Compose File** Replace every occurrence of `git.example.com`, then create `/opt/gitea/compose.yaml`: ```yaml compose.yaml theme={null} name: gitea services: gitea: image: docker.gitea.com/gitea:1-rootless restart: unless-stopped environment: GITEA__database__DB_TYPE: sqlite3 GITEA__database__PATH: /var/lib/gitea/data/gitea.db GITEA__server__DOMAIN: git.example.com GITEA__server__ROOT_URL: https://git.example.com/ GITEA__server__SSH_DOMAIN: git.example.com GITEA__server__START_SSH_SERVER: "true" GITEA__server__SSH_PORT: "2222" GITEA__server__SSH_LISTEN_PORT: "2222" GITEA__service__DISABLE_REGISTRATION: "true" volumes: - ./data:/var/lib/gitea - ./config:/etc/gitea - /etc/timezone:/etc/timezone:ro - /etc/localtime:/etc/localtime:ro ports: - "127.0.0.1:3000:3000" - "2222:2222" caddy: image: caddy:2-alpine restart: unless-stopped depends_on: - gitea ports: - "80:80" - "443:443" - "443:443/udp" volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro - caddy_data:/data - caddy_config:/config volumes: caddy_data: caddy_config: ``` The `1-rootless` tag follows Gitea's stable major channel. Port `3000` is loopback-only for diagnostics; Caddy reaches it over the private Compose network. **4. Configure HTTPS** Generate a temporary setup password hash. The command prompts without echoing the password: ```bash theme={null} sudo docker run --rm -it caddy:2-alpine caddy hash-password ``` Create `/opt/gitea/Caddyfile` and replace `REPLACE_WITH_HASH` with the command output: ```caddy Caddyfile theme={null} git.example.com { basic_auth { setup REPLACE_WITH_HASH } reverse_proxy gitea:3000 } ``` Temporary Basic Authentication prevents another visitor from claiming Gitea's installer. Caddy automatically obtains and renews the TLS certificate after DNS resolves and public ports `80` and `443` are reachable. **5. Start the Stack** ```bash theme={null} cd /opt/gitea sudo docker compose config --quiet sudo docker compose pull sudo docker compose up -d sudo docker compose ps ``` **6. Create the Administrator** Open `https://git.example.com` immediately and complete the installation wizard. Keep SQLite selected, confirm the site URL is `https://git.example.com/`, confirm the SSH port is `2222`, and create a uniquely named administrator with a generated password. Registration is disabled in the Compose environment. After signing in, enable two-factor authentication under your account security settings, add an SSH key, and confirm the installation page is no longer accessible. Remove the entire `basic_auth` block from `Caddyfile`, then validate and reload Caddy: ```bash theme={null} cd /opt/gitea sudo docker compose exec caddy caddy validate --config /etc/caddy/Caddyfile sudo docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile ``` Confirm a new private-browser session reaches Gitea without the temporary setup prompt. > [!WARNING] > > If the site unexpectedly shows an already-completed installation or an administrator you did not create, stop the stack and rebuild from a clean server. **7. Verify Web and SSH Access** ```bash theme={null} curl -fsS https://git.example.com/api/healthz ssh -T -p 2222 git@git.example.com ``` The health endpoint should return a successful status. After you add your public key in Gitea, the SSH test should identify your account and explain that shell access is not provided. ## Firewall and Port Safety Allow the VPS administration port and Gitea's separate Git SSH port before enabling UFW: ```bash theme={null} sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw allow 443/udp sudo ufw allow 2222/tcp sudo ufw enable sudo ufw status ``` Host SSH remains on port `22`; Git-over-SSH uses port `2222`. Keep port `3000` private. If every user clones over HTTPS, remove the `2222:2222` mapping and firewall rule and set `GITEA__server__DISABLE_SSH` to `"true"`. Docker-published ports can bypass some UFW forwarding rules. Publish only the ports you need, use strong SSH keys, and verify exposure from another network. ## Persistent Data and Secrets `/opt/gitea/data` contains the SQLite database, Git repositories, LFS objects, generated SSH host keys, attachments, and other application data. `/opt/gitea/config` contains `app.ini`, including generated secrets. Losing the secret key can make encrypted data such as two-factor authentication secrets unrecoverable. Keep both directories together in every backup. Do not edit `app.ini` while Gitea is running when the same setting is managed by a `GITEA__...` environment variable. Custom Git hooks are disabled by default because enabling them permits server-side code execution; leave them disabled unless you fully trust the users granted that privilege. ## Back Up and Restore Gitea's official guidance requires downtime for a consistent backup because repositories, the database, and files can change together. For this SQLite deployment, create a cold archive: ```bash theme={null} cd /opt/gitea backup_stamp="$(date -u +%Y%m%dT%H%M%SZ)" sudo install -d -m 0700 /var/backups/gitea sudo docker compose stop caddy gitea sudo tar -C /opt/gitea -czf "/var/backups/gitea/gitea-${backup_stamp}.tar.gz" data config compose.yaml Caddyfile sudo docker image inspect docker.gitea.com/gitea:1-rootless caddy:2-alpine --format '{{.RepoTags}} {{.RepoDigests}}' | sudo tee "/var/backups/gitea/images-${backup_stamp}.txt" >/dev/null sudo docker compose start gitea caddy sudo ls -lh /var/backups/gitea ``` Copy the archive and matching image manifest to encrypted storage outside the VPS. To test a restore, extract the archive into an empty `/opt/gitea` on a replacement server, restore ownership with `sudo chown -R 1000:1000 data config`, replace the floating image tags with the immutable digests recorded in the manifest, and verify repositories over both HTTPS and SSH before switching DNS. For PostgreSQL or MySQL deployments, follow Gitea's [official backup and restore guide](https://docs.gitea.com/administration/backup-and-restore/) and include a native database dump in addition to repositories and configuration. ## Update and Roll Back Safely Read the release notes and create an off-server cold backup first. Record the current image digest, then update within the stable major channel: ```bash theme={null} cd /opt/gitea sudo docker image inspect docker.gitea.com/gitea:1-rootless --format '{{index .RepoDigests 0}}' sudo docker compose pull sudo docker compose up -d sudo docker compose ps sudo docker compose logs --tail=100 gitea ``` Verify login, repository browsing, clone, fetch, push, webhooks, and LFS if enabled. Never switch between rootless and standard images by changing only the image tag; their layouts are incompatible. If a migration fails, restore the matching pre-update `data` and `config` archive and use the recorded compatible image digest rather than attempting a database-only downgrade. ## Troubleshooting | Symptom | Check | | - | - | | Gitea reports a permission error | Confirm `/opt/gitea/data` and `/opt/gitea/config` are owned by UID/GID `1000:1000`. | | Clone URLs show the wrong host or port | Recheck `ROOT_URL`, `SSH_DOMAIN`, `SSH_PORT`, and `SSH_LISTEN_PORT`, then recreate the container. | | HTTPS works but SSH clone fails | Confirm port `2222/tcp` is open, the public key is added to the correct account, and the clone URL includes `:2222`. | | Caddy cannot issue a certificate | Verify DNS, remove a stale `AAAA` record, check ports `80` and `443`, and inspect Caddy logs. | | The web UI returns an error after an update | Check Gitea logs, free disk space, and release-specific migration notes before restoring the pre-update backup. | | Pushes fail after a migration from another install type | Regenerate repository hooks as documented by Gitea after the restore. | ## Official Resources > [card] [Gitea Rootless Docker Install](https://docs.gitea.com/installation/install-with-docker-rootless) > > Official image layout, Compose examples, ports, and upgrade workflow. > [card] [Gitea Documentation](https://docs.gitea.com/) > > Current installation, administration, security, and configuration reference. > [card] [Gitea Repository](https://github.com/go-gitea/gitea) > > Upstream source, security policy, issues, and development history. > [card] [Gitea Releases](https://github.com/go-gitea/gitea/releases) > > Stable release notes, checksums, and upgrade information. > [!NOTE] > > Gitea is developed by the Gitea project and its community. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by Gitea. # Self-host Hermes Agent Source: https://docs.arct.cloud/apps/hermes-agent Deploy Hermes Agent on a Linux VPS, install it, and keep its messaging gateway running. Arct Cloud provides the Linux VPS. Hermes Agent is not preinstalled or managed by Arct Cloud. Install it with the official Nous Research tools below. Model-provider access and any related charges are separate from the VPS price. ## Choose a Plan | Plan | vCPU | RAM | NVMe storage | Best for | | - | - | - | - | - | | **cvm.pico** | 1 | 1 GB | 15 GB | Official minimum profile | | **cvm.micro** | 2 | 4 GB | 40 GB | Official recommended profile and browser tasks | Review current plan availability and pricing on the [Arct Cloud pricing page](https://www.arct.cloud/pricing). ## Steps **1. Deploy a Linux Server** [Deploy a server](/compute/virtual-machines/deploy), choose one of the plans above, and select an available Ubuntu 24.04 image. Linux images deploy in under 30 seconds. Every plan includes DDoS protection and network capacity up to 25 Gbps. **2. Connect over SSH** Find the server IP address in the Arct Cloud dashboard, then connect: ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP ``` See [Connect via SSH](/compute/virtual-machines/connect-ssh) if you need help with your key or username. **3. Install Hermes Agent** Run the official installer and follow its prompts: ```bash theme={null} curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` **4. Connect Nous Portal** Start the Portal setup and open the sign-in link shown in the terminal: ```bash theme={null} hermes setup --portal ``` Model-provider access and usage charges are separate from your Arct Cloud server. **5. Configure Messaging** Open the interactive gateway setup: ```bash theme={null} hermes gateway setup ``` Choose your messaging platform and enter the bot credentials requested by the wizard. **6. Start Hermes at Boot** Install and start the system service so the gateway returns after a server restart: ```bash theme={null} sudo hermes gateway install --system sudo hermes gateway start --system ``` **7. Verify the Gateway** Check that the service is running: ```bash theme={null} sudo hermes gateway status --system ``` ## Security Port `8642` is only needed for the optional Hermes API. Do not open it when you use Hermes only through messaging platforms. Configure a strong `API_SERVER_KEY` whenever you enable the API. If a remote client needs access, also restrict inbound traffic to trusted source addresses. Follow the official [Hermes API Server security guidance](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server) before enabling remote access. ## Official Resources > [card] [Hermes Agent Documentation](https://hermes-agent.nousresearch.com/docs/) > > Current installation, provider, gateway, and security guidance. > [card] [Hermes Agent on GitHub](https://github.com/NousResearch/hermes-agent) > > Source code, releases, and issue tracker. > [!NOTE] > > Hermes Agent is developed by Nous Research. Arct Cloud is an independent hosting provider and is not affiliated with, sponsored by, or endorsed by Nous Research. # Self-host Immich Source: https://docs.arct.cloud/apps/immich Deploy Immich on an Ubuntu VPS with the official Docker Compose stack, HTTPS, storage planning, backups, and safe upgrades. Arct Cloud provides the unmanaged Linux VPS for this deployment. Immich is not preinstalled or managed by Arct Cloud, and you are responsible for application administration, storage capacity, backups, security, and updates. > [!WARNING] > > Immich should not be the only copy of your photos or videos. Maintain independent, tested backups of both the asset files and the database. ## Choose a Plan Immich's current official minimum is 2 CPU cores and 6 GB RAM; the recommended size is 4 CPU cores and 8 GB RAM. | Arct plan | vCPU | RAM | NVMe storage | Fit | | - | -: | -: | -: | - | | **cvm.tiny** | 2 | 6 GB | 55 GB | Official minimum; small library or evaluation | | **cvm.small** | 4 | 8 GB | 75 GB | Official recommended CPU and memory profile | Thumbnails and transcoded video can add roughly 10–20% to the original library size. Check current plan resources on the [Arct Cloud pricing page](https://www.arct.cloud/pricing), leave space for the database and Docker images, and plan migration before the disk approaches capacity. ## Before You Begin Prepare the following: * A fresh Ubuntu 24.04 server * A domain or subdomain such as `photos.example.com` * An `A` record pointing that hostname to the server's public IPv4 address * Docker Engine 25 or newer with the Docker Compose plugin, installed from the [official Docker repository](https://docs.docker.com/engine/install/ubuntu/) * A reverse proxy such as Caddy or Nginx Immich requires a full virtual machine, local SSD-backed PostgreSQL storage, and the `docker compose` command. The legacy `docker-compose` command is not supported. ## Install Immich **1. Deploy and Connect** [Deploy an Ubuntu server](/compute/virtual-machines/deploy), then [connect over SSH](/compute/virtual-machines/connect-ssh). **2. Allow the Ubuntu User to Run Docker** After installing Docker Engine and the Compose plugin from Docker's official Ubuntu repository, add the default Ubuntu user to the Docker group: ```bash theme={null} sudo usermod -aG docker ubuntu exit ``` Reconnect so the group change takes effect, then verify Docker and Compose work without `sudo`: ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP docker version docker compose version ``` > [!WARNING] > > The `docker` group grants effective root access through privileged containers and host mounts. Add only trusted administrator accounts. **3. Download the Official Compose Files** ```bash theme={null} sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/immich cd /opt/immich wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env ``` These release assets are the installation method recommended by Immich for production Docker Compose deployments. **4. Configure Storage and Secrets** Edit `/opt/immich/.env` and set at least these values: ```dotenv theme={null} UPLOAD_LOCATION=/opt/immich/library DB_DATA_LOCATION=/opt/immich/postgres TZ=Etc/UTC IMMICH_VERSION=v3 DB_PASSWORD=REPLACE_WITH_A_LONG_ALPHANUMERIC_SECRET ``` Use only letters and numbers in `DB_PASSWORD`, as recommended by Immich. Keep the PostgreSQL directory on local NVMe storage; a network share is not supported for the database. Protect the environment file after editing it: ```bash theme={null} chmod 0600 /opt/immich/.env ``` **5. Keep the Application Port Private** In the `immich-server` service, bind the published port to loopback rather than every interface: ```yaml theme={null} ports: - "127.0.0.1:2283:2283" ``` Do not expose port `2283` through UFW or an external firewall. **6. Start the Stack** ```bash theme={null} cd /opt/immich docker compose pull docker compose up -d docker compose ps ``` Wait until the containers report healthy before continuing. Initial machine-learning image downloads and startup can take several minutes. **7. Create the Administrator Privately** Keep port `2283` bound to loopback. From a second terminal on your local computer, open an SSH tunnel: ```bash theme={null} ssh -N -L 2283:127.0.0.1:2283 ubuntu@YOUR_SERVER_IP ``` Open `http://127.0.0.1:2283`, create the first account, and sign in. The first account becomes the administrator. Enable multi-factor authentication, save the recovery codes separately, and review user creation and storage settings before exposing the service publicly. Stop the tunnel with Ctrl+C only after administrator access and MFA are verified. **8. Enable Public HTTPS** Install Caddy using its [official Debian and Ubuntu instructions](https://caddyserver.com/docs/install#debian-ubuntu-raspbian), then add this block to `/etc/caddy/Caddyfile`: ```caddy theme={null} photos.example.com { reverse_proxy 127.0.0.1:2283 } ``` Immich must be served from the root of a domain or subdomain, not a path such as `/immich`. ```bash theme={null} sudo caddy validate --config /etc/caddy/Caddyfile sudo systemctl reload caddy ``` Open `https://photos.example.com`, sign in with the existing administrator, and confirm MFA before inviting other users. At no point should the unauthenticated first-account screen be reachable through the public proxy. ## Firewall Allow SSH before enabling UFW: ```bash theme={null} sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable sudo ufw status ``` Only `22`, `80`, and `443` should normally be public. Keep PostgreSQL, Redis, and port `2283` private. ## Back Up and Restore Immich automatically creates database dumps under `UPLOAD_LOCATION/backups`, but those dumps do not include photos or videos. A complete recovery set requires all of the following: * A current Immich database dump * An off-server copy of the entire `UPLOAD_LOCATION`, especially `upload`, `library`, and `profile` * The contents of every external library, or a separately protected authoritative copy of those files * The protected `.env` file and every Compose or override file, including all external-library mount definitions * The exact configured image references, running image IDs, and Immich version used when the backup was created Create a restricted metadata checkpoint alongside each asset and database backup: ```bash theme={null} ( set -euo pipefail cd /opt/immich stamp="$(date -u +%Y%m%dT%H%M%SZ)" checkpoint="/var/backups/immich/${stamp}" sudo install -d -m 0700 -o "$USER" -g "$USER" "$checkpoint" cp -p .env "$checkpoint/" find . -maxdepth 1 -type f \ \( -name 'docker-compose*.yml' -o -name 'docker-compose*.yaml' \ -o -name 'compose*.yml' -o -name 'compose*.yaml' \) \ -exec cp -p {} "$checkpoint/" \; docker compose config --images >"$checkpoint/configured-images.txt" docker compose ps -q | while read -r container_id; do docker inspect --format '{{.Name}} {{.Config.Image}} {{.Image}}' \ "$container_id" done >"$checkpoint/running-images.txt" grep '^IMMICH_VERSION=' .env >"$checkpoint/immich-version.txt" chmod 0600 "$checkpoint"/* ) ``` The Compose files preserve host-to-container mount definitions for external libraries; the database dump preserves Immich's library records. Both are required to reconnect the same paths during recovery. Store this metadata checkpoint encrypted with the matching database and filesystem backup. For the most consistent filesystem copy, stop the `immich-server` container while the backup tool reads the asset directories. If the service must remain online, back up the database first and the filesystem second. Never edit files inside the Immich library directly. Follow the [official backup and restore guide](https://docs.immich.app/administration/backup-and-restore/) and perform a test restore before relying on the backup. Restores across different Immich versions can require migrations. ## Update Safely Immich supports the current stable release and does not support downgrades. Before updating, upgrade mobile clients, read the [release notes](https://github.com/immich-app/immich/releases), account for breaking changes, and create a complete backup. ```bash theme={null} cd /opt/immich docker compose pull docker compose up -d docker compose ps docker compose logs --tail=150 immich-server ``` If you pin `IMMICH_VERSION`, update it only after reviewing the target release. Restore a compatible backup instead of attempting an unsupported downgrade. ## Troubleshooting | Symptom | Check | | - | - | | A container never becomes healthy | Run `docker compose ps` and `docker compose logs`; confirm Docker Engine is current and the server meets the RAM minimum. | | Uploads fail or time out | Confirm the reverse proxy forwards WebSocket and forwarded headers, allows large request bodies, and has adequate timeouts. | | The mobile app cannot connect | Use the root URL of the HTTPS subdomain and confirm `/.well-known/immich` reaches Immich. | | PostgreSQL reports storage errors | Confirm `DB_DATA_LOCATION` is on local NVMe with free space and correct ownership. | | The disk grows faster than expected | Review original assets, thumbnails, transcoded video, database dumps, and unused Docker images separately. | ## Official Resources > [card] [Immich Installation](https://docs.immich.app/install/docker-compose/) > > Current Docker Compose files, environment settings, and post-installation guidance. > [card] [Immich on GitHub](https://github.com/immich-app/immich) > > Source code, releases, issues, and security information. > [!NOTE] > > Immich is developed independently of Arct Cloud. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by Immich or FUTO. # Self-Host n8n on a VPS Source: https://docs.arct.cloud/apps/n8n Install n8n on an Arct Cloud Linux VPS with Docker Compose, HTTPS, persistent data, backups, and safe updates. Arct Cloud provides an unmanaged Linux VPS. n8n is not preinstalled or managed by Arct Cloud; you are responsible for installation, security, backups, updates, and workflow behavior. This guide uses n8n's recommended Docker Compose deployment with Traefik on Ubuntu 24.04. Docker officially supports Ubuntu 24.04. ## Requirements | Basis | CPU and memory | Software and storage | | - | - | - | | **n8n requirements** | n8n does not publish a fixed numeric CPU or RAM minimum; requirements depend on workflow concurrency and the data each execution handles | A Linux host with Docker Engine and Docker Compose; persistent storage for `/home/node/.n8n` | | **Practical Arct recommendation** | 2 vCPUs and 4 GB RAM (`cvm.micro`) | 40 GB NVMe for a small production instance; increase RAM and storage for concurrent workflows, large binary data, or long execution retention | > [!NOTE] > > n8n is usually more sensitive to memory than CPU. Monitor actual workflow usage before increasing concurrency or adding queue-mode workers. ## Install n8n **1. Deploy Ubuntu 24.04** [Deploy a server](/compute/virtual-machines/deploy), choose a plan that fits the workload, and select Ubuntu 24.04. **2. Connect over SSH** Find the server IP address in the Arct Cloud console, then connect: ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP ``` See [Connect via SSH](/compute/virtual-machines/connect-ssh) for key and username help. **3. Point a domain to the server** Create an `A` record such as `n8n.example.com` that points to the server's public IPv4 address. Add an `AAAA` record only when IPv6 is configured and reachable on the VPS. Wait for the record to resolve to this server before starting Traefik: ```bash theme={null} getent ahostsv4 n8n.example.com ``` **4. Install Docker Engine and Compose** Install Docker from Docker's official Ubuntu repository: ```bash theme={null} sudo apt update sudo apt install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null < setup-users chmod 600 setup-users ``` `htpasswd` prompts for a temporary password without echoing it. Save that password until the owner account exists. Copy the generated encryption-key value, then create `.env`, replacing every example value: ```bash theme={null} tee .env >/dev/null <<'EOF' DOMAIN_NAME=example.com SUBDOMAIN=n8n GENERIC_TIMEZONE=Europe/Istanbul SSL_EMAIL=admin@example.com N8N_ENCRYPTION_KEY=PASTE_THE_GENERATED_VALUE_HERE EOF chmod 600 .env mkdir -p local-files ``` `N8N_ENCRYPTION_KEY` encrypts stored credentials. Keep a secure copy outside the VPS; an n8n database backup is not useful for encrypted credentials without the matching key. **6. Create the Docker Compose project** This Compose file follows n8n's official Traefik setup. It exposes only ports `80` and `443`; n8n port `5678` is bound to loopback. ```bash theme={null} tee compose.yaml >/dev/null <<'EOF' services: traefik: image: traefik restart: always command: - --providers.docker=true - --providers.docker.exposedbydefault=false - --entrypoints.web.address=:80 - --entrypoints.web.http.redirections.entrypoint.to=websecure - --entrypoints.web.http.redirections.entrypoint.scheme=https - --entrypoints.websecure.address=:443 - --certificatesresolvers.mytlschallenge.acme.tlschallenge=true - --certificatesresolvers.mytlschallenge.acme.email=${SSL_EMAIL} - --certificatesresolvers.mytlschallenge.acme.storage=/letsencrypt/acme.json ports: - "80:80" - "443:443" volumes: - traefik_data:/letsencrypt - /var/run/docker.sock:/var/run/docker.sock:ro - ./setup-users:/etc/traefik/setup-users:ro n8n: image: docker.n8n.io/n8nio/n8n restart: always ports: - "127.0.0.1:5678:5678" labels: - traefik.enable=true - traefik.http.routers.n8n.rule=Host(`${SUBDOMAIN}.${DOMAIN_NAME}`) - traefik.http.routers.n8n.tls=true - traefik.http.routers.n8n.entrypoints=web,websecure - traefik.http.routers.n8n.tls.certresolver=mytlschallenge - traefik.http.middlewares.n8n-setup-auth.basicauth.usersfile=/etc/traefik/setup-users - traefik.http.routers.n8n.middlewares=n8n-setup-auth environment: - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true - N8N_HOST=${SUBDOMAIN}.${DOMAIN_NAME} - N8N_PORT=5678 - N8N_PROTOCOL=https - N8N_WEBHOOK_URL=https://${SUBDOMAIN}.${DOMAIN_NAME}/ - N8N_PROXY_HOPS=1 - NODE_ENV=production - GENERIC_TIMEZONE=${GENERIC_TIMEZONE} - TZ=${GENERIC_TIMEZONE} - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY} - N8N_RESTRICT_FILE_ACCESS_TO=/files volumes: - n8n_data:/home/node/.n8n - ./local-files:/files volumes: n8n_data: name: n8n_data traefik_data: name: n8n_traefik_data EOF sudo docker compose config ``` > [!WARNING] > > `docker compose config` expands the environment file and can print the encryption key. Do not paste its output into tickets, chat, or public logs. **7. Create the owner behind temporary authentication** Start the containers, then confirm an unauthenticated request receives `401` from Traefik: ```bash theme={null} cd /opt/n8n sudo docker compose up -d curl -sS -o /dev/null -w '%{http_code}\n' https://n8n.example.com ``` Do not continue unless the last command returns `401`. Open `https://n8n.example.com`, enter the temporary `setup` proxy credentials, create the instance owner with a different unique password, and enable two-factor authentication in personal settings. Invite only trusted users; workflow nodes can access credentials and make network requests. After confirming that the owner can sign in with MFA, remove these three temporary lines from `compose.yaml`: ```yaml theme={null} - ./setup-users:/etc/traefik/setup-users:ro - traefik.http.middlewares.n8n-setup-auth.basicauth.usersfile=/etc/traefik/setup-users - traefik.http.routers.n8n.middlewares=n8n-setup-auth ``` Reconcile the stack and verify the proxy prompt is gone while the n8n login remains: ```bash theme={null} cd /opt/n8n sudo docker compose up -d curl -sS -o /dev/null -w '%{http_code}\n' https://n8n.example.com ``` The response must no longer be `401`. After confirming the n8n login page appears instead of the owner-creation screen, delete the temporary proxy credential file: ```bash theme={null} rm -f /opt/n8n/setup-users ``` If n8n shows its owner-creation screen again, stop and inspect the persistent `n8n_data` volume before exposing the route. **8. Verify the deployment** Confirm that both containers are running, n8n is healthy locally, and the public HTTPS endpoint responds: ```bash theme={null} cd /opt/n8n sudo docker compose ps curl -fsS http://127.0.0.1:5678/healthz curl -I https://n8n.example.com sudo docker compose logs --tail 50 n8n ``` Create a manual test workflow, run it once, and confirm that a webhook node displays the public `https://n8n.example.com/` URL. ## Data, Secrets, and Network Security | Item | Location | Backup requirement | | - | - | - | | n8n database, credentials, settings, and generated key metadata | Docker volume `n8n_data` mounted at `/home/node/.n8n` | Back up consistently; do not delete the volume during upgrades | | Explicit credential encryption key and domain settings | `/opt/n8n/.env` | Store an encrypted copy separately from the VPS | | Files used by file-processing nodes | `/opt/n8n/local-files` mounted at `/files` | Back up if workflows depend on them | | TLS certificate state | Docker volume `n8n_traefik_data` | Optional to restore; Traefik can request a new certificate when DNS is correct | Only SSH, HTTP, and HTTPS need inbound access. Restrict SSH to trusted source addresses where possible. Do not publish port `5678`; the loopback mapping is for local health checks only. > [!WARNING] > > Docker can bypass ordinary UFW rules for published container ports. The Compose file publishes only `80` and `443` publicly. Review any future `ports` additions and never expose databases, task runners, or the Docker socket to the internet. n8n stores secrets used by workflows. Use least-privilege API credentials, review community nodes before installation, prune unnecessary execution data, and run n8n's built-in security audit after initial setup and major configuration changes. ## Back Up and Restore Create portable workflow and encrypted-credential exports regularly: ```bash theme={null} cd /opt/n8n mkdir -p local-files/backups/workflows local-files/backups/credentials sudo docker compose exec -T n8n n8n export:workflow \ --backup --output=/files/backups/workflows/ sudo docker compose exec -T n8n n8n export:credentials \ --backup --output=/files/backups/credentials/ ``` These exports do not include users, settings, execution history, or every file. For a complete SQLite deployment backup, stop n8n briefly and copy its named volume: ```bash theme={null} cd /opt/n8n sudo install -d -m 700 backups sudo docker compose stop n8n sudo docker run --rm \ -v n8n_data:/source:ro \ -v /opt/n8n/backups:/backup \ alpine:3 sh -c 'tar -C /source -czf /backup/n8n-data.tgz .' sudo docker compose start n8n sudo tar -czf backups/n8n-config.tgz compose.yaml .env local-files ``` Encrypt the archives and copy them off the VPS. Test recovery on a separate server: restore `n8n-data.tgz` into a new empty volume, restore the exact `.env` encryption key and Compose file, start the same n8n version used for the backup, then verify login, credentials, workflows, and webhooks before updating. > [!NOTE] > > Never export credentials with `--decrypted` into routine backups. The default encrypted export is safer, provided you preserve `N8N_ENCRYPTION_KEY` separately. ## Update and Roll Back Safely 1. Read the [n8n release notes](https://docs.n8n.io/release-notes/) for breaking changes and update at least monthly rather than skipping many releases. 2. Record the running version and image digest: ```bash theme={null} cd /opt/n8n sudo docker compose exec -T n8n n8n --version sudo docker image inspect docker.n8n.io/n8nio/n8n \ --format '{{index .RepoDigests 0}}' ``` 3. Create and verify a full backup, including `.env` and `n8n_data`. 4. Pull the current stable image and recreate the containers: ```bash theme={null} cd /opt/n8n sudo docker compose pull sudo docker compose up -d sudo docker compose ps sudo docker compose logs --tail 100 n8n ``` 5. Verify login, credentials, a manual workflow, and a public webhook before pruning old images. Database migrations can make an older image incompatible with upgraded data. For rollback, restore the pre-update volume backup into a new empty volume and run the exact previous n8n image tag recorded before the change. Do not point an older container at the already-migrated volume and hope it will reverse migrations. ## Troubleshooting > [accordion] Traefik returns 404 or the certificate is not issued > > Confirm the `A` record resolves to this VPS and ports `80` and `443` are reachable. Check `sudo docker compose logs --tail 100 traefik`. Remove a stale `AAAA` record if IPv6 does not reach the server. > [accordion] The page returns 502 Bad Gateway > > Run `sudo docker compose -f /opt/n8n/compose.yaml ps` and inspect `sudo docker compose -f /opt/n8n/compose.yaml logs --tail 100 n8n`. Confirm `curl -fsS http://127.0.0.1:5678/healthz` succeeds. > [accordion] Webhook URLs use localhost or the wrong scheme > > Confirm `N8N_WEBHOOK_URL=https://.../` and `N8N_PROXY_HOPS=1` are present in the rendered container environment, then recreate n8n with `sudo docker compose up -d`. Avoid the deprecated `WEBHOOK_URL` variable. > [accordion] n8n restarts or workflows fail with out-of-memory errors > > Check `sudo docker stats --no-stream`, reduce workflow concurrency or binary-data size, and review execution-data retention. Resize the VPS before adding workers or memory-heavy AI and file-processing workflows. > [accordion] Credentials cannot be decrypted after a restore > > Stop n8n and restore the exact `N8N_ENCRYPTION_KEY` used by the backup. Recreating a key cannot decrypt existing credential records. ## Official Resources > [card] [n8n Docker Compose Guide](https://docs.n8n.io/deploy/host-n8n/install-options/use-a-cloud-provider/use-docker-compose/) > > Official Docker Compose, DNS, Traefik, and HTTPS setup. > [card] [n8n on GitHub](https://github.com/n8n-io/n8n) > > Source code, security policy, and issue tracker. > [card] [n8n Releases](https://github.com/n8n-io/n8n/releases) > > Stable releases, fixes, and upgrade notes. > [!NOTE] > > n8n is developed by n8n GmbH. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by n8n GmbH. # Self-host Nextcloud on a VPS Source: https://docs.arct.cloud/apps/nextcloud Deploy Nextcloud All-in-One on an Ubuntu VPS with automatic HTTPS, private administration, backups, and safe updates. Arct Cloud provides the unmanaged Linux VPS for this deployment. Nextcloud is not preinstalled or managed by Arct Cloud. You are responsible for the application, user data, access controls, backups, and updates. > [!WARNING] > > A synced copy is not a backup. Keep encrypted, tested backups outside the VPS before storing important files in Nextcloud. ## Choose a Plan Nextcloud AIO's [upstream resource guidance](https://github.com/nextcloud/all-in-one/discussions/1335) reports a minimum of 2 CPU cores, 2 GB RAM, and 40 GB system storage when any optional container is enabled. Some optional services require at least 3 GB RAM; enabling the full set requires at least 4 cores and 5 GB RAM, with 1 GB additional RAM recommended by upstream. | Profile | vCPU | RAM | NVMe storage | Guidance | | - | -: | -: | -: | - | | **Official AIO minimum with optional containers** | 2 | 2 GB | 40 GB | A technical floor, not a sizing recommendation | | **Practical Arct starting point** | 4 | 8 GB | 75 GB or more | Small teams with room for previews and selected add-ons | Your file library, previews, versions, trash, and backups determine storage needs. Size the disk for growth rather than only the initial upload. ## Before You Begin Prepare the following: * A fresh Ubuntu 24.04 server * A dedicated hostname such as `cloud.example.com` * An `A` record pointing the hostname to the server's public IPv4 address * Docker Engine with the Docker Compose plugin, installed from Docker's [official Ubuntu repository](https://docs.docker.com/engine/install/ubuntu/) * An off-server destination for encrypted backups Remove a stale `AAAA` record unless IPv6 is configured and reachable. The standard AIO setup expects its own ports and should run on a VPS without another web server or reverse proxy. ## Install Nextcloud AIO Nextcloud All-in-One is the official deployment method. The Compose configuration below follows the upstream production layout and binds the AIO management interface to loopback so it is reachable only through an SSH tunnel. **1. Deploy and Connect** [Deploy an Ubuntu server](/compute/virtual-machines/deploy), then [connect over SSH](/compute/virtual-machines/connect-ssh). **2. Verify Docker** Install Docker Engine and Compose from the official Docker repository, not the Ubuntu Snap package. Then verify both components: ```bash theme={null} sudo docker version sudo docker compose version sudo docker info | grep "Docker Root Dir" ``` Stop if the last command shows `/var/snap/docker/`; Snap-based Docker is not supported by Nextcloud AIO. **3. Create the Compose Project** ```bash theme={null} sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/nextcloud-aio cd /opt/nextcloud-aio ``` Create `/opt/nextcloud-aio/compose.yaml` with the following content: ```yaml compose.yaml theme={null} name: nextcloud-aio services: nextcloud-aio-mastercontainer: image: ghcr.io/nextcloud-releases/all-in-one:latest init: true restart: always container_name: nextcloud-aio-mastercontainer network_mode: bridge ports: - "80:80" - "127.0.0.1:8080:8080" volumes: - nextcloud_aio_mastercontainer:/mnt/docker-aio-config - /var/run/docker.sock:/var/run/docker.sock:ro volumes: nextcloud_aio_mastercontainer: name: nextcloud_aio_mastercontainer ``` Do not rename the container or the `nextcloud_aio_mastercontainer` volume. AIO relies on both names for lifecycle management and backups. **4. Start the Mastercontainer** ```bash theme={null} cd /opt/nextcloud-aio sudo docker compose pull sudo docker compose up -d sudo docker compose ps ``` **5. Open the Private AIO Interface** On your local computer, create an SSH tunnel and leave the session open: ```bash theme={null} ssh -L 8080:127.0.0.1:8080 ubuntu@YOUR_SERVER_IP ``` Open `https://127.0.0.1:8080` in your browser. The self-signed certificate warning on port `8080` is expected. Use the IP address, not your Nextcloud hostname, for this management interface. **6. Complete AIO Setup** Save the AIO passphrase in a password manager, enter `cloud.example.com`, and select only the optional containers you need. AIO creates the PostgreSQL, Redis, application, and web containers and obtains a public TLS certificate automatically. DNS must already resolve to the VPS, and public ports `80` and `443` must be reachable for certificate issuance and normal access. **7. Secure the First Login** Use the initial Nextcloud credentials shown by AIO to sign in at `https://cloud.example.com`. Immediately change the administrator password, set a recovery email, enable two-factor authentication, and review **Administration settings → Overview** for security warnings. Keep the AIO passphrase separate from the Nextcloud administrator password. Do not share either credential or expose the Docker socket through a TCP API. **8. Verify the Deployment** ```bash theme={null} curl -fsS https://cloud.example.com/status.php sudo docker ps --format 'table {{.Names}}\t{{.Status}}' ``` The status endpoint should report `installed` as `true`, and the AIO containers should remain running or healthy. ## Firewall and Port Safety Allow SSH before enabling UFW: ```bash theme={null} sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw allow 443/udp sudo ufw enable sudo ufw status ``` Port `443/udp` enables HTTP/3 and is optional. Do not open `8080`; it is intentionally bound to loopback. Port `8443` is unnecessary when you administer AIO through the SSH tunnel. If you enable Nextcloud Talk, also allow `3478/tcp` and `3478/udp` for its TURN server. Docker-published ports can bypass some UFW forwarding rules, so publish only the ports you intend to expose and verify reachability from another network. > [!WARNING] > > The read-only Docker socket mount still gives the AIO mastercontainer broad control over Docker through the socket API. Use only the official AIO image, keep this deployment on a dedicated VPS, and never expose the Docker daemon remotely. Upstream documents a manual socket-free deployment, but it removes AIO management and backup features. ## Persistent Data and Secrets AIO stores the application, PostgreSQL database, configuration, and user files in Docker volumes that it manages. Do not run `docker system prune --volumes`, delete AIO volumes, or manually edit files inside them. Protect these recovery-critical items: * The AIO passphrase * The Borg backup encryption password * The complete Borg backup archive * Any external storage mounted through the Nextcloud External Storage app, which is not included automatically in an AIO backup ## Back Up and Restore Configure the built-in BorgBackup section in the AIO interface before uploading important data. Choose a destination with enough free space, save its encryption password outside the VPS, run the first backup, and use AIO's integrity check. AIO backups include the database, files, and configuration required for a full restore. External storage configured through the External Storage app is excluded and needs its own backup. Copy or synchronize the Borg archive to another system using the [upstream lock-file guidance](https://github.com/nextcloud/all-in-one#sync-local-backups-regularly-to-another-drive) so a transfer cannot race an active backup. To test recovery, create a fresh AIO deployment, choose **Restore former AIO instance from backup**, and supply the archive location and encryption password. A backup is not proven until a restore has completed successfully. ## Update and Roll Back Safely Use the AIO interface rather than manually updating its child containers: 1. Read the AIO and Nextcloud release notes. 2. Run and verify a complete AIO backup. 3. Select **Stop containers**. 4. Apply any offered mastercontainer update. 5. Select **Start and update containers**. 6. Verify login, file upload, sync, background jobs, and **Administration settings → Overview**. AIO's `latest` channel is its tested stable channel. Do not switch to `beta` for a production instance. If an update fails, restore the full pre-update AIO backup; manually downgrading individual containers can leave the database and application versions incompatible. ## Troubleshooting | Symptom | Check | | - | - | | AIO cannot validate the domain | Confirm the `A` record, remove an incorrect `AAAA` record, ensure ports `80` and `443` are reachable, and temporarily disable a DNS proxy that interferes with validation. | | `https://127.0.0.1:8080` does not open | Confirm the SSH tunnel is still connected and `nextcloud-aio-mastercontainer` is running. The certificate warning is expected. | | The public certificate is not issued | Check DNS propagation, port conflicts, and `sudo docker logs nextcloud-aio-mastercontainer`. | | A container will not start | Review it in the AIO interface, check free RAM and disk space, and inspect its logs before restarting it. | | Talk calls fail | Verify both TCP and UDP port `3478`; DNS proxies and tunnels can prevent TURN from working. | | Updates are unavailable after a long gap | Follow AIO's manual-upgrade documentation rather than skipping several supported upgrade steps. | ## Official Resources > [card] [Nextcloud AIO Installation](https://github.com/nextcloud/all-in-one#how-to-use-this) > > Official installation, network, security, backup, and update guidance. > [card] [Nextcloud AIO Repository](https://github.com/nextcloud/all-in-one) > > Source, Compose example, security policy, and issue tracker. > [card] [Nextcloud AIO Releases](https://github.com/nextcloud/all-in-one/releases) > > Stable release notes and upgrade information. > [card] [Server Administration Manual](https://docs.nextcloud.com/server/stable/admin_manual/) > > Current Nextcloud administration and hardening reference. > [!NOTE] > > Nextcloud is developed by Nextcloud GmbH and its community. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by Nextcloud GmbH. # Self-host OpenClaw Source: https://docs.arct.cloud/apps/openclaw Run an always-on OpenClaw personal AI assistant on an Ubuntu VPS with private dashboard access, messaging, backups, and safe updates. Arct Cloud provides the unmanaged Linux VPS. OpenClaw is not preinstalled or managed by Arct Cloud. Model-provider accounts, API usage, and any channel charges are separate from the VPS price and are billed by their respective providers. > [!WARNING] > > OpenClaw is a privileged agent, not an ordinary chatbot. Depending on the tools you enable, it can read files, use credentials, browse the web, and run commands. Use a dedicated VPS, grant the minimum tools needed, and allow only trusted people to message it. ## Choose a Plan OpenClaw's [official VPS guidance](https://docs.openclaw.ai/help/faq-first-run) lists an absolute minimum of 1 vCPU, 1 GB RAM, and about 500 MB of free disk. It recommends 1–2 vCPU and 2 GB or more of RAM for logs, media, and multiple channels. | Plan | vCPU | RAM | NVMe storage | Guidance | | - | -: | -: | -: | - | | **cvm.pico** | 1 | 1 GB | 15 GB | Meets the official minimum for a basic Gateway and light use | | **cvm.nano** | 1 | 2 GB | 25 GB | Recommended starting point with memory headroom | | **cvm.micro** | 2 | 4 GB | 40 GB | Better headroom for browser automation, media, or multiple channels | Choose an Ubuntu LTS image. Browser data, sessions, media, logs, skills, and backups require more than the base installation size, so monitor memory and disk usage as the workload grows. Review current availability and pricing on the [Arct Cloud pricing page](https://www.arct.cloud/pricing). ## Before You Begin Prepare the following: * An SSH key and the public IP address from which you administer the VPS * Credentials for the model provider selected during onboarding * A model-usage budget and provider-side spending alerts * Protected off-server storage for OpenClaw backups * Optionally, a Telegram bot token from BotFather ## Install OpenClaw **1. Deploy and Connect** [Deploy an Ubuntu LTS server](/compute/virtual-machines/deploy), then [connect over SSH](/compute/virtual-machines/connect-ssh). **2. Restrict Inbound Access** A baseline OpenClaw deployment needs only SSH inbound. Configure the firewall protecting the VPS before installation: | Protocol and port | Source | | - | - | | `TCP 22` | Your current public admin IP only | Attach and verify a network-level firewall or ACL before installation. Keep the current session open and test SSH from a second terminal before disconnecting. Do not add inbound rules for `18789`, `80`, or `443`; the Gateway, model providers, and messaging channels use outbound connections for this setup. **3. Run the Official Installer** Install OpenClaw with its official Linux installer: ```bash theme={null} curl -fsSL --proto '=https' --tlsv1.2 \ https://openclaw.ai/install.sh | bash -s -- --no-onboard ``` The installer also provisions a supported Node.js runtime when required. After installation, run the canonical onboarding flow and install the managed service: ```bash theme={null} openclaw onboard --flow quickstart --install-daemon ``` Select your model provider and enter its credentials. Onboarding generates Gateway token authentication by default. Model usage is not included with the VPS. On Linux, this installs a user-level systemd service. Onboarding attempts to enable lingering so it survives logout; verify it after setup: ```bash theme={null} loginctl show-user "$USER" -p Linger ``` If the result is `Linger=no`, run `sudo loginctl enable-linger "$USER"`, then restart and recheck the Gateway. **4. Keep the Gateway Private** Retain the default loopback bind, token authentication, and port `18789`. These settings make the Gateway reachable only from the VPS itself: ```bash theme={null} openclaw config set gateway.bind loopback openclaw config set gateway.auth.mode token openclaw config set gateway.port 18789 openclaw gateway restart ``` > [!WARNING] > > Never expose port `18789` directly to the public internet. Do not change the bind to `lan`, `auto`, or a public custom address for this deployment. **5. Open the Control UI Through SSH** On your local computer, create a tunnel to the loopback-only Gateway: ```bash theme={null} ssh -N -L 18789:127.0.0.1:18789 ubuntu@YOUR_SERVER_IP ``` Keep that terminal open, then visit `http://127.0.0.1:18789/` in your local browser and authenticate with the token created during onboarding. Close the tunnel with `Ctrl+C` when finished. **6. Add Telegram (Optional)** Add the bot from a trusted SSH session: ```bash theme={null} openclaw channels add --channel telegram --token openclaw channels status --probe ``` Keep the default DM pairing policy and group allowlist. Do not switch DMs to public access or add a wildcard sender. When your account receives a pairing code, approve only the expected identity: ```bash theme={null} openclaw pairing list telegram openclaw pairing approve telegram ``` Treat the bot token as a secret and rotate it if it is exposed. **7. Verify the Deployment** Confirm that the service answers authenticated RPC calls, then run health and security checks: ```bash theme={null} openclaw gateway status --require-rpc openclaw health openclaw security audit --deep ``` Resolve security-audit findings before granting additional tools, installing third-party skills, or connecting more users. ## Security Model OpenClaw's supported posture is one user or trust boundary per Gateway. Anyone allowed to message a tool-enabled agent may be able to steer the same permissions, files, browser sessions, and credentials. Separate unrelated users or teams onto separate gateways and VPS instances. Pairing and allowlists control who can trigger the agent, but they do not eliminate prompt injection. Web pages, messages, documents, attachments, and tool output can all contain hostile instructions. Keep sensitive files outside the agent workspace, disable browser, network, filesystem, and command tools unless required, use sandboxing and approval rules, and review third-party skills and plugins as executable code. See the official [OpenClaw security guidance](https://docs.openclaw.ai/gateway/security). ## Back Up State OpenClaw state can include provider credentials, channel tokens, sessions, and workspaces. Create a verified archive, protect it like the live VPS, and copy it to encrypted off-server storage: ```bash theme={null} install -d -m 700 ~/Backups/openclaw openclaw backup create --output ~/Backups/openclaw --verify ``` Periodically test `openclaw backup verify ARCHIVE` and rehearse recovery on an isolated host. A backup left only on the VPS does not protect against server loss. ## Update Safely Create a verified backup before a significant update, then update and recheck the service: ```bash theme={null} openclaw backup create --output ~/Backups/openclaw --verify openclaw update --dry-run openclaw update openclaw doctor openclaw health openclaw gateway status --require-rpc ``` The updater's automatic configuration copy is not a full recovery point. For rollback, follow the official [update and rollback procedure](https://docs.openclaw.ai/install/updating): try a code-only rollback first, and restore older state only when the prior version cannot read the migrated state. Preserve the current state before restoring because rollback can discard changes made after the backup. ## Troubleshooting | Problem | What to check | | | - | - | - | | Control UI does not load | Confirm the SSH tunnel is still running, then run `openclaw gateway status --require-rpc` on the VPS | | | Control UI reports unauthorized | Use the token created by onboarding; do not solve auth errors by exposing the Gateway or disabling authentication | | | Gateway fails after a change | Run `openclaw doctor`, then inspect `openclaw logs --follow` | | | Telegram does not respond | Run `openclaw channels status --probe` and check `openclaw pairing list telegram` | | | Server runs out of memory | Check `free -h`, reduce browser/media work, or resize from `cvm.pico` to `cvm.nano` or `cvm.micro` | | | Port `18789` is busy | Find the existing process with \`sudo ss -ltnp | grep 18789\` before changing any port or bind setting | ## Official Resources > [card] [OpenClaw Documentation](https://docs.openclaw.ai/) > > Current installation, Gateway, channel, security, backup, and update guidance. > [card] [OpenClaw on GitHub](https://github.com/openclaw/openclaw) > > Source code, releases, security policy, and issue tracker. > [!NOTE] > > OpenClaw is developed by the OpenClaw project. Arct Cloud is an independent hosting provider and is not affiliated with, sponsored by, or endorsed by OpenClaw. # Self-hosted Apps Source: https://docs.arct.cloud/apps/overview Deploy and operate popular self-hosted applications on an Arct Cloud Linux VPS. Run automation tools, deployment platforms, monitoring services, content systems, and private data applications on an Arct Cloud Linux VPS. Arct Cloud provides the unmanaged virtual machine. The applications in these guides are not preinstalled or managed by Arct Cloud. You remain responsible for installation, domains, TLS, application security, data protection, backups, and updates. > [!NOTE] > > Plan recommendations are practical starting points, not performance guarantees. Check each application's current upstream requirements and monitor real CPU, memory, storage, and [outbound transfer usage](/compute/virtual-machines/overview) after deployment. ## Automation and Deployment > [card] [n8n](/apps/n8n) > > Run workflow automation with persistent data, HTTPS webhooks, backups, and controlled updates. > [card] [Coolify](/apps/coolify) > > Operate a self-hosted application platform on a dedicated Linux server. > [card] [Dokploy](/apps/dokploy) > > Deploy applications and databases through a Docker-based platform. > [card] [Sidekick](/apps/sidekick) > > Provision an Ubuntu VPS and deploy Dockerfile-based apps with HTTPS and encrypted secrets. > [card] [Portainer](/apps/portainer) > > Manage Docker containers, volumes, networks, and Compose stacks from a web UI. ## Operations and Analytics > [card] [Uptime Kuma](/apps/uptime-kuma) > > Monitor services and publish a private or public status page. > [card] [Umami](/apps/umami) > > Collect privacy-focused web analytics with a self-hosted PostgreSQL database. ## Content and Data > [card] [WordPress](/apps/wordpress) > > Host a WordPress site with HTTPS, backups, and an update workflow. > [card] [Nextcloud](/apps/nextcloud) > > Operate a private file-sync and collaboration service. > [card] [Paperless-ngx](/apps/paperless-ngx) > > Archive, OCR, search, and organize private documents. > [card] [Immich](/apps/immich) > > Back up and browse a private photo and video library. ## Security, Development, and AI > [card] [Vaultwarden](/apps/vaultwarden) > > Run an unofficial Bitwarden-compatible password vault with HTTPS and backups. > [card] [Gitea](/apps/gitea) > > Host private Git repositories with separate web and SSH access. > [card] [Appwrite](/apps/appwrite) > > Run a backend platform for authentication, databases, storage, and functions. > [card] [Hermes Agent](/apps/hermes-agent) > > Install Hermes Agent and keep its messaging gateway running as a service. > [card] [OpenClaw](/apps/openclaw) > > Run an always-on personal AI assistant with private dashboard access and messaging channels. ## Shared Responsibilities Every public deployment should include: * A supported Linux image and current application release * A domain with valid DNS records * HTTPS on port `443` * A firewall that exposes only required ports * Unique secrets and protected administrator accounts * Persistent storage with monitored free space * Automated off-server backups and tested restoration * A planned update window with release-note review and rollback data Start with [Deploy a Server](/compute/virtual-machines/deploy), then follow the application-specific guide above. # Self-host Paperless-ngx Source: https://docs.arct.cloud/apps/paperless-ngx Install Paperless-ngx on an Ubuntu VPS with Docker Compose, HTTPS, OCR-aware sizing, exports, and safe updates. Arct Cloud provides the unmanaged Linux VPS for this deployment. Paperless-ngx is not preinstalled or managed by Arct Cloud, and you are responsible for the application, document privacy, backups, security, and updates. > [!WARNING] > > Paperless-ngx stores potentially sensitive documents. Keep its application port private, require HTTPS, use strong account credentials, and maintain encrypted off-server backups. ## Choose a Plan Paperless-ngx does not publish a single minimum VPS size. OCR speed and memory use vary with document length, image resolution, language packs, concurrent workers, and optional services. | Arct plan | vCPU | RAM | NVMe storage | Suggested use | | - | -: | -: | -: | - | | **cvm.micro** | 2 | 4 GB | 40 GB | Personal archive and light OCR volume | | **cvm.small** | 4 | 8 GB | 75 GB | Larger imports, multiple users, or faster OCR processing | These are Arct recommendations rather than upstream requirements. Review current resources on the [Arct Cloud pricing page](https://www.arct.cloud/pricing) and leave capacity for originals, archived PDFs, thumbnails, the database, Redis, and exports. ## Before You Begin Prepare the following: * A fresh Ubuntu 24.04 server * A domain or subdomain such as `documents.example.com` * An `A` record pointing that hostname to the server's public IPv4 address * Docker Engine with the Docker Compose plugin, installed from the [official Docker repository](https://docs.docker.com/engine/install/ubuntu/) * A reverse proxy such as Caddy or Nginx Paperless-ngx supports several installation routes. This guide uses the project's official PostgreSQL Compose template and manual Compose flow so the port, database password, and application secret can be secured before any container starts. ## Install Paperless-ngx **1. Deploy and Connect** [Deploy an Ubuntu server](/compute/virtual-machines/deploy), then [connect over SSH](/compute/virtual-machines/connect-ssh). **2. Allow the Ubuntu User to Run Docker** After installing Docker Engine and the Compose plugin from Docker's official Ubuntu repository, add the default Ubuntu user to the Docker group: ```bash theme={null} sudo usermod -aG docker ubuntu exit ``` Reconnect so the group membership takes effect, then verify Docker and Compose work without `sudo`: ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP docker version docker compose version ``` > [!WARNING] > > The `docker` group grants effective root access through privileged containers and host mounts. Add only trusted administrator accounts. **3. Download the Official Compose Templates** Create the application directory and download the three files from Paperless-ngx's official PostgreSQL Compose example: ```bash theme={null} sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/paperless cd /opt/paperless curl -fsSLo docker-compose.yml \ https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml curl -fsSLo docker-compose.env \ https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env curl -fsSLo .env \ https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env ``` Review these files and compare their URLs with the current [official setup documentation](https://docs.paperless-ngx.com/setup/#docker) before continuing. **4. Secure the Template Before First Start** Patch the official template while it is still offline. This binds Paperless to loopback, replaces the template PostgreSQL password, and passes the same password to the webserver: ```bash theme={null} cd /opt/paperless sed -i 's| - "8000:8000"| - "127.0.0.1:8000:8000"|' \ docker-compose.yml sed -i 's| POSTGRES_PASSWORD: paperless| POSTGRES_PASSWORD: ${PAPERLESS_DB_PASSWORD:?set PAPERLESS_DB_PASSWORD in .env}|' \ docker-compose.yml sed -i '/ PAPERLESS_DBENGINE: postgresql/a\ PAPERLESS_DBPASS: ${PAPERLESS_DB_PASSWORD:?set PAPERLESS_DB_PASSWORD in .env}' \ docker-compose.yml ``` Generate separate database and application secrets, configure the public URL, and lock both environment files to the current user: ```bash theme={null} umask 077 database_password="$(openssl rand -hex 32)" application_secret="$(openssl rand -hex 48)" printf '\nPAPERLESS_DB_PASSWORD=%s\n' "$database_password" >>.env sed -i "s/^PAPERLESS_SECRET_KEY=.*/PAPERLESS_SECRET_KEY=${application_secret}/" \ docker-compose.env sed -i 's|^#PAPERLESS_URL=.*|PAPERLESS_URL=https://documents.example.com|' \ docker-compose.env unset database_password application_secret chmod 0600 .env docker-compose.env install -d -m 0700 export install -d -m 0750 consume ``` Validate the security-critical changes before pulling or starting anything: ```bash theme={null} grep -F '127.0.0.1:8000:8000' docker-compose.yml grep -F 'PAPERLESS_DB_PASSWORD' docker-compose.yml test "$(stat -c '%a' docker-compose.env)" = 600 test "$(stat -c '%a' .env)" = 600 test "$(stat -c '%a' export)" = 700 if grep -Eq '^[[:space:]]*-[[:space:]]*"8000:8000"' docker-compose.yml; then echo 'Refusing to start: Paperless would bind to every interface.' >&2 exit 1 fi docker compose config --quiet ``` > [!WARNING] > > Do not run `docker compose up` unless every validation above succeeds. The upstream template's unmodified `8000:8000` mapping publishes the first-login screen on every network interface. **5. Start the Private Stack and Create the Superuser** Only after the loopback and secret checks pass, start the stack and create the initial superuser from the server terminal: ```bash theme={null} cd /opt/paperless docker compose pull docker compose up -d docker compose ps docker compose run --rm webserver createsuperuser ``` From a second terminal on your local computer, tunnel to the loopback-only service: ```bash theme={null} ssh -N -L 8000:127.0.0.1:8000 ubuntu@YOUR_SERVER_IP ``` Open `http://127.0.0.1:8000`, sign in with the superuser, and verify the private installation. Stop the tunnel with Ctrl+C after the check. **6. Enable HTTPS** Install Caddy using its [official Debian and Ubuntu instructions](https://caddyserver.com/docs/install#debian-ubuntu-raspbian), then add this block to `/etc/caddy/Caddyfile`: ```caddy theme={null} documents.example.com { reverse_proxy 127.0.0.1:8000 } ``` ```bash theme={null} sudo caddy validate --config /etc/caddy/Caddyfile sudo systemctl reload caddy ``` **7. Verify and Harden the Account** Open `https://documents.example.com` and sign in with the superuser created privately. Create a non-superuser account for routine document work, restrict user permissions, and keep the superuser for administration only. ```bash theme={null} docker compose ps docker compose logs --tail=100 webserver ``` ## Firewall and OCR Controls Allow SSH before enabling UFW: ```bash theme={null} sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable sudo ufw status ``` Do not expose Paperless port `8000`, PostgreSQL, or Redis publicly. For limited servers, reduce concurrent workers, avoid unnecessary OCR language packs, keep `PAPERLESS_OCR_MODE` at its default, and consider limiting OCR pages or image-cleaning work according to the [upstream low-resource guidance](https://docs.paperless-ngx.com/setup/#less-powerful-devices). ## Back Up and Restore Pause new document consumption before exporting. The official exporter includes documents, thumbnails, metadata, settings, and database content in the Compose `export` directory. Keep that directory mode `0700` and require it to be empty so old plaintext exports are not mixed into a new recovery set: ```bash theme={null} cd /opt/paperless chmod 0700 export test -z "$(find export -mindepth 1 -maxdepth 1 -print -quit)" || { echo 'Move or remove the previous plaintext export before continuing.' >&2 exit 1 } docker compose exec -T webserver document_exporter ../export ``` Encrypt the export and deployment configuration before it leaves the VPS. The example below uses an `age` recipient public key; keep the matching private identity off the Paperless server: ```bash theme={null} sudo apt update sudo apt install -y age ( set -euo pipefail cd /opt/paperless stamp="$(date -u +%Y%m%dT%H%M%SZ)" plaintext="/tmp/paperless-${stamp}.tar.gz" encrypted="${plaintext}.age" metadata="/tmp/paperless-${stamp}-image.txt" docker inspect "$(docker compose ps -q webserver)" \ --format '{{.Config.Image}} {{.Image}}' >"$metadata" tar -czf "$plaintext" \ export docker-compose.yml docker-compose.env .env \ -C /tmp "$(basename "$metadata")" age -r 'age1REPLACE_WITH_YOUR_BACKUP_RECIPIENT' \ -o "$encrypted" "$plaintext" sha256sum "$encrypted" printf 'Encrypted backup ready: %s\n' "$encrypted" ) ``` Copy only the `.age` file to off-server storage and compare its SHA-256 hash at the destination. After the remote copy is verified, remove the short-lived local plaintext, local encrypted staging file, metadata file, and exporter output: ```bash theme={null} rm -f -- /tmp/paperless-*.tar.gz /tmp/paperless-*.tar.gz.age \ /tmp/paperless-*-image.txt find /opt/paperless/export -mindepth 1 -delete ``` Unlinking files cannot guarantee physical erasure on SSD storage, so use encrypted storage and keep plaintext retention as short as possible. API tokens are not included and must be created again after a restore. Exports are version-specific; the encrypted archive includes the exact webserver image metadata and the protected Compose environment files used for that backup. Restore with the official `document_importer` into an empty installation running a compatible version. Review the [backup and restore documentation](https://docs.paperless-ngx.com/administration/#making-backups) and test the full procedure before relying on it. ## Update Safely Read the [release notes](https://github.com/paperless-ngx/paperless-ngx/releases) and any referenced migration guide. Stop consumption, create an off-server export, then update the Compose deployment: ```bash theme={null} docker compose down docker compose pull docker compose up -d docker compose ps docker compose logs --tail=150 webserver ``` Container startup applies database migrations. Do not interrupt migrations or attempt a downgrade against a migrated database; restore a compatible pre-update backup instead. ## Troubleshooting | Symptom | Check | | - | - | | OCR jobs are slow or the server swaps | Reduce worker concurrency and optional OCR processing, then monitor CPU, RAM, and free disk. | | Files remain in the consume directory | Check consumer logs, directory ownership, `USERMAP_UID`/`USERMAP_GID`, and whether the filesystem supports inotify. | | Login redirects to HTTP or the wrong host | Confirm `PAPERLESS_URL` matches the public HTTPS URL and reload the containers. | | Caddy returns `502` | Confirm the webserver is healthy and bound to `127.0.0.1:8000`. | | An update fails | Stop, inspect webserver/database logs and release notes, and restore the matching backup rather than repeatedly restarting migrations. | ## Official Resources > [card] [Paperless-ngx Setup](https://docs.paperless-ngx.com/setup/) > > Official installation routes, Compose templates, and low-resource guidance. > [card] [Paperless-ngx on GitHub](https://github.com/paperless-ngx/paperless-ngx) > > Source code, releases, issues, and security policy. > [!NOTE] > > Paperless-ngx is developed independently of Arct Cloud. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by the Paperless-ngx project. # Install Portainer on a VPS Source: https://docs.arct.cloud/apps/portainer Deploy Portainer Community Edition on an Arct Cloud Linux VPS with Docker, a domain, HTTPS, backups, and a safe update workflow. Arct Cloud provides an unmanaged Linux VPS. Portainer is not preinstalled or managed by Arct Cloud; you are responsible for installation, security, backups, updates, and the containers it controls. This guide installs Portainer Community Edition (CE) on Ubuntu 24.04 using Portainer's supported Docker Compose method. Docker officially supports Ubuntu 24.04. ## Requirements | Basis | CPU and memory | Software and storage | | - | - | - | | **Portainer requirements** | Portainer does not publish a numeric CPU or RAM minimum for Docker Standalone | A currently supported Docker version, `sudo` access, a supported architecture, and persistent storage for `/data` | | **Practical Arct recommendation** | 2 vCPUs and 4 GB RAM (`cvm.micro`) | 40 GB NVMe for Portainer and a small number of light containers; size for the workloads Portainer will manage | Portainer validates specific Docker versions for each release. Check the [current compatibility table](https://docs.portainer.io/start/requirements-and-prerequisites) before upgrading Docker or Portainer. ## Install Portainer **1. Deploy Ubuntu 24.04** [Deploy a server](/compute/virtual-machines/deploy), select a plan that meets your workload requirements, and choose Ubuntu 24.04. **2. Connect over SSH** Find the server IP address in the Arct Cloud console, then connect: ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP ``` See [Connect via SSH](/compute/virtual-machines/connect-ssh) for key and username help. **3. Point a domain to the server** Create an `A` record such as `portainer.example.com` that points to the server's public IPv4 address. Add an `AAAA` record only if IPv6 is configured on the server. Wait until the record resolves before requesting a certificate: ```bash theme={null} getent ahostsv4 portainer.example.com ``` **4. Install Docker Engine** Install Docker from Docker's official Ubuntu repository. Do not install Docker through Snap; Portainer warns that the Snap package can cause compatibility issues. ```bash theme={null} sudo apt update sudo apt install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null </dev/null <<'EOF' services: portainer: container_name: portainer image: portainer/portainer-ce:lts restart: always volumes: - /var/run/docker.sock:/var/run/docker.sock - portainer_data:/data ports: - "127.0.0.1:9443:9443" volumes: portainer_data: name: portainer_data EOF sudo docker compose config ``` **6. Start Portainer and claim the admin account privately** Start the container only when you are ready to complete setup: ```bash theme={null} cd /opt/portainer sudo docker compose up -d ``` From a **second terminal on your local computer**, open an SSH tunnel and leave it running: ```bash theme={null} ssh -N -L 9443:127.0.0.1:9443 ubuntu@YOUR_SERVER_IP ``` Open `https://localhost:9443`. The certificate warning is expected because Portainer uses a self-signed certificate on this private connection. Create the first administrator with a unique password of at least 12 characters, then select the automatically detected local Docker environment. Close the tunnel with `Ctrl+C` only after setup is complete. > [!WARNING] > > Portainer allows five minutes to create the first administrator. If setup times out, run `sudo docker restart portainer`, reconnect the SSH tunnel, and complete setup within the next five minutes. **7. Configure the public reverse proxy and HTTPS** Replace `portainer.example.com` in both commands with your domain. Portainer serves a self-signed certificate on its loopback-only backend; Nginx terminates the public, trusted certificate. ```bash theme={null} sudo apt install -y nginx certbot python3-certbot-nginx sudo tee /etc/nginx/sites-available/portainer >/dev/null <<'EOF' server { listen 80; listen [::]:80; server_name portainer.example.com; location / { proxy_pass https://127.0.0.1:9443; proxy_ssl_verify off; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 3600; } } EOF sudo ln -s /etc/nginx/sites-available/portainer \ /etc/nginx/sites-enabled/portainer sudo nginx -t sudo systemctl reload nginx sudo certbot --nginx -d portainer.example.com ``` If UFW is enabled, allow SSH before enabling only the public web ports: ```bash theme={null} sudo ufw allow OpenSSH sudo ufw allow 'Nginx Full' sudo ufw enable ``` **8. Verify the deployment** Confirm that the container, loopback backend, and public endpoint respond: ```bash theme={null} cd /opt/portainer sudo docker compose ps curl -kI https://127.0.0.1:9443 curl -I https://portainer.example.com sudo docker logs --tail 50 portainer ``` ## Persistent Data and Security The `portainer_data` volume contains Portainer's database and configuration. Registry credentials, endpoint configuration, and other sensitive settings stored by Portainer must be treated as secrets. Keep any downloaded backup encrypted and outside the VPS. > [!WARNING] > > Mounting `/var/run/docker.sock` gives Portainer control equivalent to root over this Docker host. Limit administrator access, use a unique password, and never publish the Docker API on ports `2375` or `2376` for this setup. Only ports `80` and `443` need to be publicly reachable. Port `9443` is bound to `127.0.0.1`; legacy HTTP port `9000` is not enabled. Port `8000` is needed only for Portainer Edge Agents. If you later enable Edge features, follow Portainer's current networking guidance and restrict exposure wherever possible. Docker-published ports can bypass UFW rules. Keeping the Portainer mapping on loopback prevents direct access even when Docker manages its own firewall rules. ## Back Up and Restore 1. In Portainer, open **Settings** and find **Back up Portainer**. 2. Enable password protection, use a unique backup password, and download the `tar.gz` archive. 3. Store the archive and its password separately from the VPS. 4. Test restoration on a fresh Portainer instance with an empty data volume. On the initialization screen, expand **Restore Portainer from backup** and select the archive. > [!NOTE] > > A Portainer configuration backup covers data in Portainer's `/data` volume. It does not back up the containers, Compose files, application volumes, or databases that Portainer manages. Back up those workloads independently. ## Update Safely Use the LTS channel for routine production updates: 1. Read the [release notes](https://github.com/portainer/portainer/releases) and compatibility matrix. 2. Download an encrypted Portainer configuration backup and back up every managed workload separately. 3. Record the current image digest: ```bash theme={null} sudo docker image inspect portainer/portainer-ce:lts \ --format '{{index .RepoDigests 0}}' ``` 4. Pull and recreate the container, preserving `portainer_data`: ```bash theme={null} cd /opt/portainer sudo docker compose pull sudo docker compose up -d sudo docker compose ps sudo docker logs --tail 100 portainer ``` 5. Confirm login and local environment access before pruning old images. Portainer can migrate its database during an update. Do not point an older image at a migrated `portainer_data` volume. To roll back, deploy the previous supported image against a fresh empty volume and restore the pre-update Portainer backup during initialization. ## Troubleshooting > [accordion] The public URL returns 502 Bad Gateway > > Check `sudo docker compose -f /opt/portainer/compose.yaml ps` and `sudo docker logs --tail 100 portainer`. Confirm that `curl -kI https://127.0.0.1:9443` succeeds, then run `sudo nginx -t`. > [accordion] Portainer says the instance timed out > > Restart it with `sudo docker restart portainer`, reload the page, and create the administrator within five minutes. Do not delete the data volume. > [accordion] The browser reports a certificate or domain error > > Verify that the DNS `A` record resolves to this VPS, ports `80` and `443` are reachable, and `sudo certbot certificates` lists the expected domain. Do not browse directly to port `9443`; its backend certificate is self-signed. > [accordion] The local Docker environment is unavailable > > Confirm the socket mount with `sudo docker inspect portainer --format '{{json .Mounts}}'` and check that Docker is running with `sudo systemctl status docker`. Rootless Docker needs separate Portainer configuration and has limitations. ## Official Resources > [card] [Portainer Documentation](https://docs.portainer.io/start/install-ce/server/docker/linux) > > Official Docker Standalone installation and networking guidance. > [card] [Portainer on GitHub](https://github.com/portainer/portainer) > > Source code, security policy, and issue tracker. > [card] [Portainer Releases](https://github.com/portainer/portainer/releases) > > LTS releases, fixes, and upgrade notes. > [!NOTE] > > Portainer is developed by Portainer.io. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by Portainer.io. # Deploy Apps with Sidekick Source: https://docs.arct.cloud/apps/sidekick Provision an Ubuntu VPS and deploy Dockerfile-based apps with Sidekick, Traefik, automatic TLS, and encrypted secrets. Sidekick is an open-source deployment CLI that runs on your local computer. It builds an application from its `Dockerfile`, transfers the image to an Ubuntu VPS over SSH, and runs it behind Traefik with automatic HTTPS. It is a lightweight alternative to a web-based deployment panel. Arct Cloud provides the unmanaged virtual machine. Sidekick and the applications it deploys are not preinstalled or managed by Arct Cloud; you remain responsible for server security, application data, backups, updates, and recovery. ## Requirements | Basis | CPU | RAM | Storage | Operating system | | - | -: | -: | -: | - | | **Official Sidekick minimum** | No numeric minimum published | No numeric minimum published | No numeric minimum published | Ubuntu LTS | | **Practical Arct starting point** | 2 vCPUs | 4 GB | 40 GB NVMe (`cvm.micro`) | Ubuntu 24.04 LTS | The practical recommendation is suitable for Sidekick, Traefik, and one lightweight application. Size the server for the applications you deploy, and allow additional storage for Docker images and application logs. On your local computer, you also need: * Homebrew, Sidekick, SOPS, and age * A running Docker engine * An SSH agent with the private key selected during server deployment * `ssh`, `scp`, and `rsync` * An application with a working `Dockerfile` * A domain name, or Sidekick's default `sslip.io` hostname for testing > [!WARNING] > > Sidekick is best suited to stateless, single-container applications on one server. It generates its own Compose definition without persistent volumes. Use an external database and object storage for persistent state, or choose a platform with a documented stateful backup and restore workflow. ## Install Sidekick and Deploy an App **1. Deploy a fresh Ubuntu server** [Deploy a server](/compute/virtual-machines/deploy), select Ubuntu 24.04 LTS, and add an SSH key. Use a fresh VPS because `sidekick init` upgrades packages, installs Docker, and configures Traefik to own ports `80` and `443`. Do not install Nginx, Caddy, or another Traefik instance on the same server before initialization. **2. Restrict inbound access** Attach and verify a network-level firewall or ACL before running Sidekick: | Ports | Source | Purpose | | - | - | - | | `22/tcp` | Your current public admin IP only | SSH administration and deployments | | `80/tcp` | Any | HTTP redirect and ACME certificate issuance | | `443/tcp` | Any | HTTPS application traffic | | All other inbound ports | Deny | Open only when a workload explicitly requires one | Sidekick does not currently configure a firewall or rate limits. Application ports are routed inside Docker and should not be opened on the host. **3. Bootstrap the Sidekick account** Arct Cloud Ubuntu images use `ubuntu` as the default SSH user, while Sidekick initializes through either `root` or an existing `sidekick` account. Connect as `ubuntu` and create the account without enabling root SSH: ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP sudo useradd -m -s /bin/bash -G sudo sidekick echo 'sidekick ALL=(ALL) NOPASSWD: ALL' \ | sudo tee /etc/sudoers.d/sidekick >/dev/null sudo chmod 0440 /etc/sudoers.d/sidekick sudo visudo -cf /etc/sudoers.d/sidekick sudo install -d -o sidekick -g sidekick -m 0700 /home/sidekick/.ssh sudo install -o sidekick -g sidekick -m 0600 \ /home/ubuntu/.ssh/authorized_keys \ /home/sidekick/.ssh/authorized_keys exit ``` From your local computer, verify both key access and passwordless sudo: ```bash theme={null} ssh sidekick@YOUR_SERVER_IP 'sudo -n true && echo "Sidekick account ready"' ``` > [!WARNING] > > The `sidekick` account receives passwordless sudo and later joins the Docker group. Either permission is effectively root-level access. Protect the SSH key and keep port `22` restricted. **4. Prepare your local computer** Install the current release and its secret-management dependencies with Homebrew: ```bash theme={null} brew install sidekick sops age sidekick --version docker version ``` Make sure Docker is running. Sidekick requires an SSH agent even when a key exists in the default `.ssh` directory: ```bash theme={null} ssh-add -l ssh-add ~/.ssh/id_ed25519 ``` Replace the key path when you use a different key. The first SSH connection records the server host key; verify its fingerprint before accepting it. **5. Initialize the VPS** Run the initializer on your local computer: ```bash theme={null} sidekick init ``` Enter the VPS IPv4 address and an email address for ACME certificate notices. Current Sidekick versions may also ask you to name the VPS. The initializer connects as `sidekick`, updates Ubuntu, installs Docker and the server-side encryption tools, and starts Traefik. Sidekick stores the age private key in its local configuration. Restrict and back up that file immediately: ```bash theme={null} chmod 600 ~/.config/sidekick/default.yaml ``` Keep an encrypted off-device copy. The matching age private key is required to decrypt the encrypted environment file stored on the VPS. **6. Verify the server** Start a new SSH session so Docker group membership takes effect, then inspect the installation: ```bash theme={null} ssh sidekick@YOUR_SERVER_IP docker version docker compose version docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' ``` Confirm that Traefik is running and only expected ports are published. Do not assume the initializer disabled root or password authentication. Keep this session open and add an early SSH configuration drop-in: ```bash theme={null} sudo tee /etc/ssh/sshd_config.d/00-sidekick-hardening.conf >/dev/null <<'EOF' PermitRootLogin no PasswordAuthentication no KbdInteractiveAuthentication no EOF sudo chmod 0644 /etc/ssh/sshd_config.d/00-sidekick-hardening.conf sudo sshd -t sudo systemctl reload ssh sudo sshd -T | grep -E 'permitrootlogin|passwordauthentication|kbdinteractiveauthentication' ``` Verify that all three effective values are `no`. From a second local terminal, confirm `ssh sidekick@YOUR_SERVER_IP` still works before closing the original session. Use the Arct Cloud VNC console if you lose SSH access. **7. Prepare DNS and the application** For a custom hostname such as `app.example.com`, create an `A` record pointing to the VPS public IPv4 address. Add an `AAAA` record only when IPv6 is configured and reachable. In the application directory, confirm that: * `Dockerfile` builds successfully on your local Docker engine * The application listens on `0.0.0.0`, not only `127.0.0.1` * You know the container's HTTP port * `.env` is excluded from Git Test the build before deploying: ```bash theme={null} docker build -t sidekick-test . ``` **8. Launch the application** From the directory containing `Dockerfile`, run: ```bash theme={null} sidekick launch ``` Provide these values when prompted: | Prompt | Example | Notes | | - | - | - | | Application name | `myapp` | Use a URL-safe, unique name | | Application port | `3000` | The HTTP port inside the container, not a host port | | Domain | `app.example.com` | Must resolve to this VPS; accept the generated `sslip.io` host for testing | | Environment file | `.env` | Optional; Sidekick encrypts it with SOPS and age before transfer | Sidekick builds the Linux image locally, transfers it directly to the VPS without a registry, creates the Compose service, and routes the hostname through Traefik. It writes deployment metadata to `sidekick.yml` in the project directory. **9. Verify HTTPS** Wait for DNS and certificate issuance, then check the public endpoint: ```bash theme={null} curl -I https://app.example.com ``` Confirm the certificate hostname, application logs, and a representative request before sending production traffic. ## Deploy Updates and Previews Run a normal update from the application directory: ```bash theme={null} sidekick deploy ``` Sidekick rebuilds the image locally, transfers it over SSH, updates encrypted environment values when they changed, and replaces the running application. Test application-level health after every deployment; Sidekick cannot determine whether every business workflow is healthy. Preview deployments require a clean Git worktree and use the current commit hash: ```bash theme={null} sidekick preview sidekick preview list sidekick preview remove ``` Track `sidekick.yml` after reviewing it, but never commit `.env` or the global Sidekick configuration. With a custom application domain, preview URLs are subdomains of that hostname, so configure matching DNS records before relying on previews. Sidekick's generated `sslip.io` hostname is simpler for initial testing. ## Security, Data, and Maintenance * Sidekick's firewall and rate-limiting support is not implemented. Keep the upstream network policy in place and review it whenever a workload changes. * The `sidekick` account, Docker daemon, and Traefik's Docker socket are privileged infrastructure. A compromised deployment key can compromise every workload on the VPS. * Sidekick-managed applications share the external `sidekick` Docker network. Do not treat that network as isolation between mutually untrusted applications. * Store durable data in a separately backed-up service. Sidekick does not create or back up persistent volumes for the generated application service. * Back up `~/.config/sidekick/default.yaml`, each project's `sidekick.yml`, DNS records, and all external data stores. Test restoration on a replacement VPS. * Before `brew upgrade sidekick`, review the [release notes](https://github.com/MightyMoud/sidekick/releases) and keep a recoverable copy of configuration and application data. Patch Ubuntu and monitor `df -h` and `docker system df` regularly. > [!NOTE] > > Sidekick's released documentation and current source can differ. Check `sidekick --help` for the commands installed on your workstation and review upstream changes before using it for a critical workload. ## Troubleshooting > [accordion] Sidekick cannot connect over SSH > > Confirm port `22` allows your current public IP, `ssh sidekick@YOUR_SERVER_IP` succeeds, `ssh-add -l` lists the correct key, and `sudo -n true` works for the `sidekick` account. Resolve host-key warnings instead of disabling verification. > [accordion] Initialization fails on ports 80 or 443 > > Run `sudo ss -lntp | grep -E ':(80|443) '` on the VPS. Stop or remove the conflicting reverse proxy before retrying; Sidekick's Traefik must own both ports. > [accordion] HTTPS certificate issuance fails > > Confirm the `A` record resolves to this VPS and ports `80` and `443` are reachable. Do not proxy the record through another service until the direct Sidekick route works. > [accordion] Traefik returns 502 Bad Gateway > > Confirm the port entered during `sidekick launch` matches the application's container port and the process listens on `0.0.0.0`. Inspect `docker ps` and the application container logs over SSH. > [accordion] The local image build fails > > Confirm Docker is running and build the same `Dockerfile` manually with `docker build -t sidekick-test .`. Fix the first build error before rerunning Sidekick. > [accordion] A preview hostname does not resolve > > Preview URLs prepend a commit hash to the application hostname. Add wildcard DNS for the custom hostname or use the generated `sslip.io` hostname while testing. ## Official Resources > [card] [Sidekick Documentation](https://www.sidekickdeploy.com/docs/introduction/what-is-sidekick/) > > Official concepts, commands, and design documentation. > [card] [Sidekick on GitHub](https://github.com/MightyMoud/sidekick) > > Source code, roadmap, license, and issue tracker. > [card] [Sidekick Releases](https://github.com/MightyMoud/sidekick/releases) > > Release binaries and version history. > [!NOTE] > > Sidekick is developed by the Sidekick project. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by Sidekick. # Install Umami Analytics on a VPS Source: https://docs.arct.cloud/apps/umami Self-host Umami Analytics on an Arct Cloud Linux VPS with Docker, PostgreSQL, HTTPS, protected secrets, backups, and safe updates. Arct Cloud provides an unmanaged Linux VPS. Umami is not preinstalled or managed by Arct Cloud; you are responsible for installation, privacy configuration, database operations, security, backups, and updates. This guide installs the current Umami release on Ubuntu 24.04 using Umami's official Docker Compose architecture: the Umami application plus PostgreSQL. ## Requirements | Basis | CPU and memory | Software and storage | | - | - | - | | **Umami requirements** | Umami does not publish a numeric CPU or RAM minimum | For source installs: Node.js 18.18 or newer and PostgreSQL 12.14 or newer; the official Compose stack bundles the runtime and PostgreSQL 15 | | **Practical Arct recommendation** | 2 vCPUs and 4 GB RAM (`cvm.micro`) | 40 GB NVMe for a small site or low-traffic portfolio; use more storage and memory as traffic and retention grow | Analytics volume, retention, and concurrent dashboard queries determine real resource use. Monitor PostgreSQL growth rather than treating the starting plan as a fixed production limit. ## Install Umami **1. Deploy Ubuntu 24.04** [Deploy a server](/compute/virtual-machines/deploy), select a plan that meets your traffic and retention needs, and choose Ubuntu 24.04. **2. Connect over SSH** Find the server IP address in the Arct Cloud console, then connect: ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP ``` See [Connect via SSH](/compute/virtual-machines/connect-ssh) for help with keys or usernames. **3. Point a domain to the server** Create an `A` record such as `analytics.example.com` pointing to the VPS's public IPv4 address. Add an `AAAA` record only if IPv6 is configured. Confirm the record resolves before requesting a certificate: ```bash theme={null} getent ahostsv4 analytics.example.com ``` **4. Install Docker Engine** Install Docker Engine and the Compose plugin from Docker's official Ubuntu repository: ```bash theme={null} sudo apt update sudo apt install -y ca-certificates curl openssl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null < .env chmod 600 .env ``` > [!WARNING] > > Do not commit `.env`, paste it into support tickets, or regenerate it during routine updates. Preserve it with your encrypted backups. **6. Create the official-style Compose stack** The configuration follows Umami's current upstream Compose file, with secrets moved to `.env` and application port `3000` restricted to loopback. PostgreSQL has no published host port. ```bash theme={null} cd /opt/umami tee compose.yaml >/dev/null <<'EOF' services: umami: image: ghcr.io/umami-software/umami:latest restart: always init: true ports: - "127.0.0.1:3000:3000" environment: DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@db:5432/umami APP_SECRET: ${APP_SECRET} depends_on: db: condition: service_healthy healthcheck: test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"] interval: 5s timeout: 5s retries: 5 db: image: postgres:15-alpine restart: always environment: POSTGRES_DB: umami POSTGRES_USER: umami POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - umami-db-data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"] interval: 5s timeout: 5s retries: 5 volumes: umami-db-data: EOF sudo docker compose config --quiet ``` **7. Start Umami and secure the default account privately** Start Umami while port `3000` is still reachable only on server loopback: ```bash theme={null} cd /opt/umami sudo docker compose up -d ``` From a **second terminal on your local computer**, open an SSH tunnel and leave it running: ```bash theme={null} ssh -N -L 3000:127.0.0.1:3000 ubuntu@YOUR_SERVER_IP ``` Open `http://localhost:3000` and sign in with Umami's initial credentials: | Username | Password | | - | - | | `admin` | `umami` | Change the default password immediately, then create a separate account for routine use if your team needs shared access. Never embed an administrator credential in a website's tracking code. Close the tunnel with `Ctrl+C` only after the default password has been changed. **8. Configure the public reverse proxy and HTTPS** Replace `analytics.example.com` with your domain: ```bash theme={null} sudo apt install -y nginx certbot python3-certbot-nginx sudo tee /etc/nginx/sites-available/umami >/dev/null <<'EOF' server { listen 80; listen [::]:80; server_name analytics.example.com; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } EOF sudo ln -s /etc/nginx/sites-available/umami \ /etc/nginx/sites-enabled/umami sudo nginx -t sudo systemctl reload nginx sudo certbot --nginx -d analytics.example.com ``` If UFW is enabled, allow SSH and the reverse proxy: ```bash theme={null} sudo ufw allow OpenSSH sudo ufw allow 'Nginx Full' sudo ufw enable ``` **9. Verify the deployment** Confirm both containers are healthy and the local and public endpoints respond: ```bash theme={null} cd /opt/umami sudo docker compose ps curl -fsS http://127.0.0.1:3000/api/heartbeat curl -I https://analytics.example.com sudo docker compose logs --tail 50 umami db ``` Add a website in Umami, copy its tracking snippet into that site's ``, visit the site, and confirm that a pageview appears in the realtime view. ## Persistent Data, Secrets, and Ports The `umami-db-data` Docker volume contains all analytics and account data. `/opt/umami/.env` contains the PostgreSQL password and `APP_SECRET`; changing `APP_SECRET` invalidates existing authentication tokens. Keep both the database backup and `.env` encrypted and stored outside the VPS. Only ports `80` and `443` need inbound public access. Port `3000` is loopback-only, and PostgreSQL port `5432` is not published at all. Do not add a public `5432` mapping. Website tracking requests arrive through the same HTTPS endpoint as the dashboard. > [!NOTE] > > Self-hosting gives you control of the analytics database, but you remain responsible for your privacy notice, retention policy, access controls, and any laws that apply to your visitors. ## Back Up and Restore Create a consistent [logical PostgreSQL backup](https://www.postgresql.org/docs/current/app-pgdump.html) and preserve the matching secrets: ```bash theme={null} cd /opt/umami install -d -m 700 backups umami_backup_stamp=$(date +%F-%H%M%S) sudo docker compose exec -T db \ pg_dump -U umami -d umami -Fc \ > "backups/umami-${umami_backup_stamp}.dump" cp -p .env "backups/secrets-${umami_backup_stamp}.env" sudo docker image inspect ghcr.io/umami-software/umami:latest \ --format '{{index .RepoDigests 0}}' \ > "backups/app-image-${umami_backup_stamp}.txt" sudo docker compose exec -T db postgres --version \ > "backups/postgres-version-${umami_backup_stamp}.txt" chmod 600 backups/* ``` Copy the dump, `.env`, application digest, and PostgreSQL version record to encrypted storage outside the VPS. Test restoration before relying on the backup. > [!WARNING] > > Never test a restore over the live database. Use a replacement VPS or an isolated Compose project with a new, empty PostgreSQL volume. On the replacement stack, restore the saved `.env`, set the Umami image to the recorded immutable digest, and use the same PostgreSQL major version. Start only the empty database, then restore the dump into it: ```bash theme={null} cd /opt/umami sudo docker compose up -d --wait db sudo docker compose exec -T db \ pg_restore -U umami -d umami --exit-on-error \ < /path/to/umami-backup.dump sudo docker compose up -d --wait umami sudo docker compose ps curl -fsS http://127.0.0.1:3000/api/heartbeat sudo docker compose logs --tail 100 umami ``` Verify login, historical reports, and new realtime events through an SSH tunnel to the replacement VPS. Switch DNS or the reverse-proxy upstream only after those checks pass. Keep the original stack intact until the replacement is serving traffic correctly; update it only after the restore has been proven. ## Update Safely Umami's official Compose file follows its current `latest` application channel. Treat each pull as a deployment: 1. Read the [Umami releases](https://github.com/umami-software/umami/releases) and migration notes. 2. Create a PostgreSQL dump and copy `.env` off the server. 3. Record the current application image digest: ```bash theme={null} sudo docker image inspect ghcr.io/umami-software/umami:latest \ --format '{{index .RepoDigests 0}}' ``` 4. Pull and recreate the containers: ```bash theme={null} cd /opt/umami sudo docker compose pull sudo docker compose up -d sudo docker compose ps sudo docker compose logs --tail 100 umami db ``` 5. After a major Umami upgrade, refresh PostgreSQL planner statistics as recommended upstream: ```bash theme={null} sudo docker compose exec -T db \ psql -U umami -d umami -c 'ANALYZE;' ``` 6. Verify login, realtime collection, and historical reports before pruning old images. Application startup can migrate the database. Do not run an older Umami image against a database already migrated by a newer release. For rollback, build a replacement stack with the previous image digest, the same PostgreSQL major version, the saved `.env`, and a new empty volume. Restore the pre-update dump, verify it through an SSH tunnel, then switch traffic; keep the migrated stack available until rollback is confirmed. ## Troubleshooting > [accordion] The Umami container is unhealthy > > Run `sudo docker compose -f /opt/umami/compose.yaml ps` and inspect `sudo docker compose -f /opt/umami/compose.yaml logs --tail 100 umami db`. The database must become healthy before Umami starts; also check disk space with `df -h`. > [accordion] Umami cannot authenticate to PostgreSQL > > Confirm `POSTGRES_PASSWORD` exists in `/opt/umami/.env` and that `sudo docker compose config` resolves the same value for the app and database. Changing the Compose environment does not change the password inside an already initialized PostgreSQL volume; update the database role deliberately or restore the original `.env`. > [accordion] The dashboard loads but no pageviews appear > > Confirm the snippet uses this Umami domain and the correct website ID. In the browser network panel, look for blocked script or collection requests; content blockers commonly block analytics. Test without a blocker and verify the public URL uses a valid HTTPS certificate. > [accordion] Nginx returns 502 Bad Gateway > > Confirm `curl -fsS http://127.0.0.1:3000/api/heartbeat` works, then run `sudo nginx -t`. If the app is still starting migrations, follow its logs instead of repeatedly restarting it. ## Official Resources > [card] [Umami Documentation](https://docs.umami.is/docs/install) > > Official installation, configuration, and update guidance. > [card] [Umami on GitHub](https://github.com/umami-software/umami) > > Source code, Compose file, security policy, and issue tracker. > [card] [Umami Releases](https://github.com/umami-software/umami/releases) > > Current releases, changes, and upgrade context. > [!NOTE] > > Umami is developed by Umami Software and its contributors. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by Umami Software. # Install Uptime Kuma on a VPS Source: https://docs.arct.cloud/apps/uptime-kuma Run Uptime Kuma 2 on an Arct Cloud Linux VPS with Docker, HTTPS, persistent monitoring data, backups, and safe updates. Arct Cloud provides an unmanaged Linux VPS. Uptime Kuma is not preinstalled or managed by Arct Cloud; you are responsible for installation, monitor configuration, security, backups, and updates. This guide installs the stable Uptime Kuma 2 major channel on Ubuntu 24.04 using the project's official Docker Compose method. ## Requirements | Basis | CPU and memory | Software and storage | | - | - | - | | **Uptime Kuma requirements** | The project does not publish a numeric CPU or RAM minimum | Docker on a major Linux distribution and local storage with POSIX file-lock support for `/app/data`; NFS is not supported | | **Practical Arct recommendation** | 2 vCPUs and 4 GB RAM (`cvm.micro`) | 40 GB NVMe for a modest number of monitors and retention; increase resources for many monitors, short intervals, or long history | Resource use depends on monitor type, check frequency, retained heartbeats, and notification integrations. Start conservatively and watch memory and disk use after importing your monitors. ## Install Uptime Kuma **1. Deploy Ubuntu 24.04** [Deploy a server](/compute/virtual-machines/deploy), select an appropriately sized plan, and choose Ubuntu 24.04. **2. Connect over SSH** Find the server IP address in the Arct Cloud console, then connect: ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP ``` See [Connect via SSH](/compute/virtual-machines/connect-ssh) if you need help with keys or usernames. **3. Point a dedicated domain to the server** Uptime Kuma does not support being served from a subdirectory. Create an `A` record such as `status.example.com` pointing to the server's public IPv4 address. Add an `AAAA` record only when IPv6 is configured. Confirm the record resolves: ```bash theme={null} getent ahostsv4 status.example.com ``` **4. Install Docker Engine** Install Docker and the Compose plugin from Docker's official Ubuntu repository: ```bash theme={null} sudo apt update sudo apt install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null </dev/null <<'EOF' services: uptime-kuma: container_name: uptime-kuma image: louislam/uptime-kuma:2 restart: unless-stopped volumes: - ./data:/app/data ports: - "127.0.0.1:3001:3001" EOF sudo docker compose config ``` > [!WARNING] > > Keep `/opt/uptime-kuma/data` on the VPS's local NVMe filesystem. NFS and other filesystems without reliable POSIX locks can corrupt Uptime Kuma's SQLite database. **6. Start Uptime Kuma and create the administrator privately** Start Uptime Kuma while it is still reachable only on server loopback: ```bash theme={null} cd /opt/uptime-kuma sudo docker compose up -d ``` From a **second terminal on your local computer**, open an SSH tunnel and leave it running: ```bash theme={null} ssh -N -L 3001:127.0.0.1:3001 ubuntu@YOUR_SERVER_IP ``` Open `http://localhost:3001`, create the administrator with a unique password, and enable two-factor authentication in **Settings → Security**. Leave authentication enabled unless a tested external access-control layer will protect the entire dashboard. Close the tunnel with `Ctrl+C` after the administrator and two-factor authentication are configured. **7. Configure the public reverse proxy and HTTPS** Replace `status.example.com` with your domain. The WebSocket headers are required by Uptime Kuma. ```bash theme={null} sudo apt install -y nginx certbot python3-certbot-nginx sudo tee /etc/nginx/sites-available/uptime-kuma >/dev/null <<'EOF' server { listen 80; listen [::]:80; server_name status.example.com; location / { proxy_pass http://127.0.0.1:3001; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 3600; } } EOF sudo ln -s /etc/nginx/sites-available/uptime-kuma \ /etc/nginx/sites-enabled/uptime-kuma sudo nginx -t sudo systemctl reload nginx sudo certbot --nginx -d status.example.com ``` If UFW is enabled, allow SSH and the reverse proxy: ```bash theme={null} sudo ufw allow OpenSSH sudo ufw allow 'Nginx Full' sudo ufw enable ``` After `https://status.example.com` works, sign in with the secured administrator account. Open **Settings → Reverse Proxy → HTTP Headers** and enable **Trust Proxy** so forwarded client addresses are handled correctly. **8. Verify the deployment** ```bash theme={null} cd /opt/uptime-kuma sudo docker compose ps sudo docker inspect uptime-kuma --format '{{.State.Health.Status}}' curl -I http://127.0.0.1:3001 curl -I https://status.example.com sudo docker logs --tail 50 uptime-kuma ``` Add a test HTTP monitor and configure a notification channel. Trigger its **Test** action before depending on it for alerts. ## Ports, Probes, and Secrets Only ports `80` and `443` need inbound public access. Port `3001` remains on `127.0.0.1`. Uptime Kuma normally initiates outbound checks, so a monitor's destination port must be allowed outbound; you do not need to open that port inbound on the Uptime Kuma server. Monitor URLs, credentials, notification tokens, two-factor settings, and history are stored under `/opt/uptime-kuma/data`. Protect backups as secrets. Do not mount the Docker socket merely to monitor public endpoints; access to that socket is effectively root access to the host. For email notifications on Arct Cloud, use a provider's authenticated submission endpoint on port `587`. Outbound ports `25` and `465` are blocked by default. ## Back Up and Restore Uptime Kuma 2 removed the old JSON backup and restore feature. The project's supported backup method is to stop Uptime Kuma and copy its complete data directory. Create a consistent archive: ```bash theme={null} cd /opt/uptime-kuma sudo install -d -m 700 /var/backups/uptime-kuma uptime_backup_stamp=$(date +%F-%H%M%S) sudo docker compose stop uptime-kuma sudo stat -c '%u:%g %a %n' data data/kuma.db | sudo tee \ "/var/backups/uptime-kuma/ownership-${uptime_backup_stamp}.txt" >/dev/null sudo tar --acls --xattrs -czf \ "/var/backups/uptime-kuma/data-${uptime_backup_stamp}.tar.gz" data sudo docker compose start uptime-kuma ``` Copy the archive and matching ownership file to encrypted storage outside the VPS and test them periodically. To restore, use the same Uptime Kuma major version, stop the service, preserve the current directory, and extract the selected archive with its ACLs, extended attributes, and numeric ownership: ```bash theme={null} cd /opt/uptime-kuma sudo docker compose down sudo mv data "data.before-restore.$(date +%F-%H%M%S)" sudo tar --acls --xattrs --numeric-owner -xzf /path/to/data-backup.tar.gz sudo stat -c '%u:%g %a %n' data data/kuma.db ``` Compare the restored `uid:gid` and mode with the matching `ownership-*.txt` file before starting the container. If they match, start and verify Uptime Kuma: ```bash theme={null} sudo docker compose up -d sudo docker logs --tail 100 uptime-kuma ``` The renamed directory makes the restore reversible. Confirm monitors, history, users, and notification settings before removing it. ## Update Safely The `2` tag receives stable v2 updates. Before every update: 1. Read the [release notes](https://github.com/louislam/uptime-kuma/releases), especially migration notes. 2. Stop the service and take a complete data-directory backup as described above. 3. Record the current immutable image digest: ```bash theme={null} sudo docker image inspect louislam/uptime-kuma:2 \ --format '{{index .RepoDigests 0}}' ``` 4. Pull and recreate the service: ```bash theme={null} cd /opt/uptime-kuma sudo docker compose pull sudo docker compose up -d --force-recreate sudo docker compose ps sudo docker logs --tail 100 uptime-kuma ``` 5. Verify the dashboard, one monitor, and one notification test before pruning the previous image. Database migrations can make an in-place downgrade unsafe. For rollback, stop the service, restore the pre-update `data` archive, and recreate the container with the previously recorded image digest. Never interrupt a documented major-version migration; restore the pre-migration backup if it fails. ## Troubleshooting > [accordion] Nginx returns 502 Bad Gateway > > Run `sudo docker compose -f /opt/uptime-kuma/compose.yaml ps`, inspect `sudo docker logs --tail 100 uptime-kuma`, and confirm `curl -I http://127.0.0.1:3001` succeeds. > [accordion] The dashboard says it cannot connect to the socket server > > Confirm the Nginx configuration includes `proxy_http_version 1.1` plus the `Upgrade` and `Connection` headers. If a CDN is in front, enable WebSocket support there too. > [accordion] The container restarts or reports SQLite locking errors > > Confirm `/opt/uptime-kuma/data` is on local storage, not NFS. Check free space with `df -h /opt/uptime-kuma` and memory with `free -h`, then inspect the container logs before restarting it. > [accordion] Email notification tests fail > > Use authenticated SMTP submission on port `587`, verify DNS resolution and provider credentials, and check whether the provider requires a specific sender address. Ports `25` and `465` are blocked by default on Arct Cloud. ## Official Resources > [card] [Uptime Kuma Installation](https://github.com/louislam/uptime-kuma/wiki/%F0%9F%94%A7-How-to-Install) > > Official Docker, Compose, storage, and reverse-proxy guidance. > [card] [Uptime Kuma on GitHub](https://github.com/louislam/uptime-kuma) > > Source code, security policy, and issue tracker. > [card] [Uptime Kuma Releases](https://github.com/louislam/uptime-kuma/releases) > > Stable releases, breaking changes, and migration notes. > [!NOTE] > > Uptime Kuma is developed by its open-source maintainers. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by the Uptime Kuma project. # Self-host Vaultwarden Source: https://docs.arct.cloud/apps/vaultwarden Install Vaultwarden on an Ubuntu VPS with Docker, HTTPS, restricted sign-ups, backups, and a safe update workflow. Arct Cloud provides the unmanaged Linux VPS for this deployment. Vaultwarden is not preinstalled or managed by Arct Cloud, and you are responsible for the application, its data, security, and updates. > [!WARNING] > > A password vault is security-critical infrastructure. Use HTTPS, enable multi-factor authentication, keep tested off-server backups, and apply security updates promptly. ## Choose a Plan Vaultwarden does not publish a fixed minimum server size. These are practical starting points for the container and its local SQLite database, not upstream requirements. | Arct plan | vCPU | RAM | NVMe storage | Suggested use | | - | -: | -: | -: | - | | **cvm.nano** | 1 | 2 GB | 25 GB | Personal or small-family vault | | **cvm.micro** | 2 | 4 GB | 40 GB | More users, attachments, or operational headroom | Review current resources on the [Arct Cloud pricing page](https://www.arct.cloud/pricing) before deployment. ## Before You Begin Prepare the following: * A fresh Ubuntu 24.04 server * A domain or subdomain such as `vault.example.com` * An `A` record pointing that hostname to the server's public IPv4 address * Docker Engine with the Docker Compose plugin, installed from the [official Docker repository](https://docs.docker.com/engine/install/ubuntu/) * A reverse proxy such as Caddy or Nginx for HTTPS Only ports `22`, `80`, and `443` need to be reachable publicly. Keep Vaultwarden's internal port private. ## Install Vaultwarden **1. Deploy and Connect** [Deploy an Ubuntu server](/compute/virtual-machines/deploy), then [connect over SSH](/compute/virtual-machines/connect-ssh). **2. Allow the Ubuntu User to Run Docker** After installing Docker Engine and the Compose plugin from Docker's official Ubuntu repository, add the default Ubuntu user to the Docker group: ```bash theme={null} sudo usermod -aG docker ubuntu exit ``` Reconnect so the new group membership takes effect, then verify both commands work without `sudo`: ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP docker version docker compose version ``` > [!WARNING] > > Membership in the `docker` group is effectively root access because it can start privileged containers and mount the host filesystem. Add only trusted administrator accounts. **3. Create the Application Directory** ```bash theme={null} sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/vaultwarden cd /opt/vaultwarden ``` **4. Create the Compose File** Replace `vault.example.com` with your hostname. ```yaml compose.yaml theme={null} services: vaultwarden: image: vaultwarden/server:latest container_name: vaultwarden restart: unless-stopped environment: DOMAIN: "https://vault.example.com" SIGNUPS_ALLOWED: "true" volumes: - ./data:/data ports: - "127.0.0.1:8000:80" ``` The bind mount keeps the vault database, keys, attachments, and configuration under `/opt/vaultwarden/data`. **5. Start Vaultwarden** ```bash theme={null} docker compose pull docker compose up -d docker compose ps ``` Do not publish port `8000` through your cloud firewall or UFW. **6. Create the First Account Privately** Do not publish the proxy yet. Keep Vaultwarden bound to loopback and, from a second terminal on your local computer, create an SSH tunnel: ```bash theme={null} ssh -N -L 8000:127.0.0.1:8000 ubuntu@YOUR_SERVER_IP ``` Open `http://127.0.0.1:8000`, create the first account, sign in, and enable authenticator-app (TOTP) two-step login before continuing. Save the recovery code somewhere separate from the vault. Back in the VPS session, close registration and force Compose to recreate the service with the new environment value: ```bash theme={null} cd /opt/vaultwarden sed -i 's/SIGNUPS_ALLOWED: "true"/SIGNUPS_ALLOWED: "false"/' compose.yaml docker compose up -d --force-recreate vaultwarden docker inspect vaultwarden --format '{{range .Config.Env}}{{println .}}{{end}}' \ | grep -Fx 'SIGNUPS_ALLOWED=false' ``` Stop the local tunnel with Ctrl+C only after the account, TOTP login, and disabled registration are verified. Leave the `/admin` page disabled unless you have a specific need for it. If you enable it, follow Vaultwarden's official guidance and use a hashed `ADMIN_TOKEN`. **7. Enable Public HTTPS** Install Caddy using its [official Debian and Ubuntu instructions](https://caddyserver.com/docs/install#debian-ubuntu-raspbian), then add this site block to `/etc/caddy/Caddyfile`: ```caddy theme={null} vault.example.com { reverse_proxy 127.0.0.1:8000 } ``` Validate and reload the configuration: ```bash theme={null} sudo caddy validate --config /etc/caddy/Caddyfile sudo systemctl reload caddy ``` Caddy obtains and renews the TLS certificate after DNS resolves and ports `80` and `443` are reachable. Open `https://vault.example.com`, sign in, and confirm two-step login is enforced. Registration must already be disabled before the hostname becomes public. ## Firewall Allow SSH before enabling UFW so you do not lock yourself out: ```bash theme={null} sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable sudo ufw status ``` ## Back Up and Restore The `/data` directory is the authoritative persistent state. Stop the container before creating a filesystem archive so the SQLite database is consistent: ```bash theme={null} ( set -euo pipefail cd /opt/vaultwarden sudo install -d -m 0700 /var/backups/vaultwarden stamp="$(date -u +%Y%m%dT%H%M%SZ)" temporary="/var/backups/vaultwarden/.vaultwarden-${stamp}.tar.gz.tmp" archive="/var/backups/vaultwarden/vaultwarden-${stamp}.tar.gz" stopped=false restart_if_needed() { if [ "$stopped" = true ]; then if docker compose start vaultwarden; then stopped=false else echo 'CRITICAL: Vaultwarden did not restart; start it manually.' >&2 fi fi } trap restart_if_needed EXIT trap 'exit 130' INT trap 'exit 143' TERM docker compose stop vaultwarden stopped=true sudo tar -czf "$temporary" data compose.yaml sudo tar -tzf "$temporary" >/dev/null sudo chmod 0600 "$temporary" sudo mv "$temporary" "$archive" docker compose start vaultwarden stopped=false trap - EXIT INT TERM printf 'Validated backup: %s\n' "$archive" ) ``` The timestamp is UTC with second-level precision. The archive is validated before an atomic rename on the same filesystem, and the exit trap restarts Vaultwarden if archive creation or validation fails. Copy the archive to encrypted storage outside the VPS and test restoration regularly. A backup left only on the same server does not protect against server or disk loss. Review the [official backup guidance](https://github.com/dani-garcia/vaultwarden/wiki/Backing-up-your-vault) before automating the process. ## Update Safely Read the [Vaultwarden release notes](https://github.com/dani-garcia/vaultwarden/releases), create an off-server backup, then update: ```bash theme={null} cd /opt/vaultwarden docker compose pull docker compose up -d docker compose ps docker compose logs --tail=100 vaultwarden ``` Do not downgrade a database unless the release notes explicitly document a supported rollback path. Restore a tested pre-update backup instead. ## Troubleshooting | Symptom | Check | | - | - | | The web vault reports an insecure context | Confirm the public URL uses HTTPS and `DOMAIN` exactly matches it. | | Caddy cannot issue a certificate | Verify DNS, ports `80` and `443`, and that no other service is using those ports. | | New users can still register | Confirm `SIGNUPS_ALLOWED` is `false`, then recreate the container with `docker compose up -d`. | | A client cannot connect | Check `docker compose ps`, Vaultwarden logs, proxy logs, and the configured server URL in the client. | ## Official Resources > [card] [Vaultwarden Repository](https://github.com/dani-garcia/vaultwarden) > > Official container examples, releases, security policy, and project documentation. > [card] [Vaultwarden Wiki](https://github.com/dani-garcia/vaultwarden/wiki) > > Reverse proxy, backup, admin-page, and configuration guidance. > [!NOTE] > > Vaultwarden is an unofficial Bitwarden-compatible server and is not associated with Bitwarden, Inc. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by Vaultwarden or Bitwarden. # Self-host WordPress on a VPS Source: https://docs.arct.cloud/apps/wordpress Deploy WordPress on an Ubuntu VPS with the official container image, MySQL, automatic HTTPS, backups, and secure updates. Arct Cloud provides the unmanaged Linux VPS for this deployment. WordPress is not preinstalled or managed by Arct Cloud. You are responsible for WordPress administration, plugins, themes, security, backups, email delivery, and updates. Arct Cloud does not provide WordPress application support. > [!NOTE] > > Moving an existing site rather than starting a new one? See [WordPress Migration](/migration/wordpress), which builds on this stack. ## Choose a Plan WordPress does not publish a universal CPU, RAM, or disk minimum because resource use depends heavily on traffic, caching, themes, plugins, and media. Its [official modern software baseline](https://wordpress.org/about/requirements/) is PHP 8.3 or newer, MariaDB 10.11+ or MySQL 8.0+, and HTTPS. | Profile | vCPU | RAM | NVMe storage | Guidance | | - | -: | -: | -: | - | | **Practical minimum** | 1 | 2 GB | 25 GB | A small, cached site with a limited plugin set | | **Recommended Arct starting point** | 2 | 4 GB | 40 GB or more | More headroom for updates, traffic spikes, and media processing | These are Arct deployment recommendations, not official WordPress hardware requirements. Monitor memory, CPU, database size, and media growth after launch. ## Before You Begin Prepare the following: * A fresh Ubuntu 24.04 server * A hostname such as `www.example.com` * An `A` record pointing the hostname to the server's public IPv4 address * Docker Engine with the Docker Compose plugin, installed from Docker's [official Ubuntu repository](https://docs.docker.com/engine/install/ubuntu/) * An external SMTP provider if the site must send reliable email The stack below uses the Docker Official Image for WordPress with PHP 8.3 and Apache, MySQL 8.4, and Caddy 2. Only Caddy publishes web ports; WordPress and MySQL remain private on the Compose network. ## Install WordPress **1. Deploy and Connect** [Deploy an Ubuntu server](/compute/virtual-machines/deploy), then [connect over SSH](/compute/virtual-machines/connect-ssh). **2. Create the Project and Database Secret** ```bash theme={null} sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/wordpress cd /opt/wordpress install -d -m 0700 secrets openssl rand -hex 32 > secrets/db_password chmod 600 secrets/db_password ``` Keep the secret file out of source control and never paste it into a support ticket. **3. Create the Compose File** Create `/opt/wordpress/compose.yaml`: ```yaml compose.yaml theme={null} name: wordpress services: db: image: mysql:8.4 restart: unless-stopped environment: MYSQL_DATABASE: wordpress MYSQL_USER: wordpress MYSQL_PASSWORD_FILE: /run/secrets/db_password MYSQL_RANDOM_ROOT_PASSWORD: "1" secrets: - db_password volumes: - db_data:/var/lib/mysql wordpress: image: wordpress:php8.3-apache restart: unless-stopped depends_on: - db environment: WORDPRESS_DB_HOST: db:3306 WORDPRESS_DB_USER: wordpress WORDPRESS_DB_NAME: wordpress WORDPRESS_DB_PASSWORD_FILE: /run/secrets/db_password WORDPRESS_CONFIG_EXTRA: | define('DISALLOW_FILE_EDIT', true); define('FORCE_SSL_ADMIN', true); secrets: - db_password volumes: - wordpress_data:/var/www/html caddy: image: caddy:2-alpine restart: unless-stopped depends_on: - wordpress ports: - "80:80" - "443:443" - "443:443/udp" volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro - caddy_data:/data - caddy_config:/config secrets: db_password: file: ./secrets/db_password volumes: db_data: wordpress_data: caddy_data: caddy_config: ``` The image tags follow supported stable channels while pinning the PHP, MySQL, and Caddy major or minor line. Review compatibility before changing any of them. **4. Configure the Domain and HTTPS** Generate a temporary setup password hash. The command prompts without echoing the password: ```bash theme={null} sudo docker run --rm -it caddy:2-alpine caddy hash-password ``` Create `/opt/wordpress/Caddyfile`, replace the example hostname, and replace `REPLACE_WITH_HASH` with the command output: ```caddy Caddyfile theme={null} www.example.com { basic_auth { setup REPLACE_WITH_HASH } encode zstd gzip reverse_proxy wordpress:80 } ``` Temporary Basic Authentication prevents another visitor from claiming the public WordPress installer. Caddy obtains and renews the TLS certificate automatically after DNS resolves and ports `80` and `443` are reachable. The official WordPress image recognizes the forwarded HTTPS scheme. **5. Start the Stack** ```bash theme={null} cd /opt/wordpress sudo docker compose config --quiet sudo docker compose pull sudo docker compose up -d sudo docker compose ps ``` MySQL can take a minute to initialize on the first start. Follow progress with `sudo docker compose logs -f --tail=100` and press `Ctrl+C` after the services settle. **6. Complete the First Login Securely** Open `https://www.example.com` and complete the WordPress installer. Use a unique administrator username other than `admin`, a generated password, and a monitored email address. After signing in: * Install all offered core, theme, and plugin updates. * Remove unused plugins and themes. * Keep the built-in file editor disabled through `WORDPRESS_CONFIG_EXTRA`. * Enable two-factor authentication with a well-maintained plugin from the official WordPress plugin directory. * Configure authenticated SMTP and test password-reset email before inviting other users. Remove the entire `basic_auth` block from `Caddyfile`, then validate and reload Caddy: ```bash theme={null} cd /opt/wordpress sudo docker compose exec caddy caddy validate --config /etc/caddy/Caddyfile sudo docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile ``` Confirm a new private-browser session reaches WordPress without the temporary setup prompt. **7. Verify the Deployment** ```bash theme={null} curl -fsSI https://www.example.com cd /opt/wordpress sudo docker compose ps sudo docker compose logs --tail=50 caddy wordpress db ``` Confirm the response uses HTTPS, no service is restarting, and the WordPress dashboard reports the expected site URL. ## Firewall and Port Safety Allow SSH before enabling UFW: ```bash theme={null} sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw allow 443/udp sudo ufw enable sudo ufw status ``` Port `443/udp` is optional and enables HTTP/3 through Caddy. Do not publish MySQL port `3306` or the WordPress container's port `80`. Docker-published ports can bypass some UFW forwarding rules; this Compose file intentionally publishes only Caddy's public ports. ## Persistent Data and Secrets The `wordpress_data` volume contains WordPress core files, uploads, themes, and plugins. The `db_data` volume contains the MySQL database. A recoverable backup requires both at the same point in time. The database password is stored in `/opt/wordpress/secrets/db_password` and mounted with Compose secrets. Keep `/opt/wordpress`, the backup set, and any copied configuration private. Do not add phpMyAdmin or expose the database merely for convenience. ## Back Up and Restore Create a maintenance window and back up both the database and WordPress files. Stopping Caddy prevents new public requests while the snapshot is created: ```bash theme={null} cd /opt/wordpress set -o errexit -o nounset -o pipefail backup_stamp="$(date -u +%Y%m%dT%H%M%SZ)" backup_dir="/var/backups/wordpress" sudo install -d -m 0700 "$backup_dir" restart_caddy() { sudo docker compose start caddy >/dev/null; } trap restart_caddy EXIT sudo docker compose stop caddy sudo docker compose exec -T db sh -c 'exec mysqldump --no-tablespaces --single-transaction --quick -uwordpress -p"$(cat /run/secrets/db_password)" wordpress' | sudo tee "$backup_dir/.database-${backup_stamp}.sql.tmp" >/dev/null sudo docker compose exec -T wordpress tar -C /var/www/html -czf - . | sudo tee "$backup_dir/.files-${backup_stamp}.tar.gz.tmp" >/dev/null sudo tar -C /opt/wordpress -czf "$backup_dir/.config-${backup_stamp}.tar.gz.tmp" compose.yaml Caddyfile secrets sudo docker image inspect wordpress:php8.3-apache mysql:8.4 caddy:2-alpine --format '{{.RepoTags}} {{.RepoDigests}}' | sudo tee "$backup_dir/.images-${backup_stamp}.txt.tmp" >/dev/null sudo test -s "$backup_dir/.database-${backup_stamp}.sql.tmp" sudo test -s "$backup_dir/.files-${backup_stamp}.tar.gz.tmp" sudo test -s "$backup_dir/.config-${backup_stamp}.tar.gz.tmp" sudo test -s "$backup_dir/.images-${backup_stamp}.txt.tmp" sudo mv "$backup_dir/.database-${backup_stamp}.sql.tmp" "$backup_dir/database-${backup_stamp}.sql" sudo mv "$backup_dir/.files-${backup_stamp}.tar.gz.tmp" "$backup_dir/files-${backup_stamp}.tar.gz" sudo mv "$backup_dir/.config-${backup_stamp}.tar.gz.tmp" "$backup_dir/config-${backup_stamp}.tar.gz" sudo mv "$backup_dir/.images-${backup_stamp}.txt.tmp" "$backup_dir/images-${backup_stamp}.txt" restart_caddy trap - EXIT sudo ls -lh "$backup_dir" ``` Copy the complete timestamped set to encrypted storage outside the VPS and keep several generations. The configuration archive contains the database password and must remain private; the image manifest records the exact images needed for a reproducible rollback. Test restoration on a separate deployment: restore the file archive into an empty WordPress volume, import the matching SQL dump into an empty database, then verify URLs, media, users, and plugins before changing DNS. Do not restore only the files or only the database. Follow the [official WordPress backup guidance](https://developer.wordpress.org/advanced-administration/security/backup/) for retention and database-specific alternatives. ## Update and Roll Back Safely WordPress in the official image is self-managing inside its persistent volume. Apply WordPress core, plugin, and theme updates from the dashboard after creating a full backup. To update the PHP/Apache, MySQL, and Caddy container images within their pinned channels: ```bash theme={null} cd /opt/wordpress sudo docker compose pull sudo docker compose up -d sudo docker compose ps sudo docker compose logs --tail=100 wordpress db caddy ``` Read WordPress release notes and plugin compatibility information before major changes. Keep MySQL on its current major line unless you have reviewed the database vendor's upgrade path. A safe rollback restores the matching pre-update database and files together and pins the Compose images to the digests recorded in that backup set; replacing only the container image cannot reverse a WordPress database migration. ## Troubleshooting | Symptom | Check | | - | - | | Caddy cannot issue a certificate | Verify the `A` record, remove a stale `AAAA` record, confirm ports `80` and `443`, and check `docker compose logs caddy`. | | WordPress shows “Error establishing a database connection” | Wait for first-time MySQL initialization, then check `db` logs, the secret mount, database name, and free disk space. | | The browser reports a redirect loop | Confirm the public URL is HTTPS and Caddy proxies directly to `wordpress:80`; do not add a second TLS proxy without configuring forwarded headers. | | Uploads or updates fail | Check free disk space and permissions in the `wordpress_data` volume, then review the WordPress container logs. | | Email never arrives | The container does not provide reliable outbound mail by itself; configure authenticated SMTP and inspect the SMTP provider's delivery logs. | | The site is slow | Check CPU, RAM, database queries, image sizes, plugin count, page caching, and external API calls before resizing. | ## Official Resources > [card] [WordPress Requirements](https://wordpress.org/about/requirements/) > > Current PHP, database, web server, and HTTPS requirements. > [card] [WordPress Docker Image](https://hub.docker.com/_/wordpress) > > Official image tags, Compose example, secrets, and reverse-proxy behavior. > [card] [WordPress Documentation](https://wordpress.org/documentation/) > > Installation, administration, updates, and troubleshooting guidance. > [card] [WordPress Releases](https://wordpress.org/download/releases/) > > Official release archive and version history. > [card] [WordPress Development Repository](https://github.com/WordPress/wordpress-develop) > > Upstream development source, tests, and issue references. > [!NOTE] > > WordPress is a trademark of the WordPress Foundation. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by the WordPress Foundation or the WordPress project. # Billing Cycles Source: https://docs.arct.cloud/billing/billing-cycles Review billing options and order totals. Choose a billing option when you deploy a server. The console shows the periods currently available, the order total, and any applicable discount. ## Before You Pay * Confirm the selected plan * Review the billing period and order total * Choose a payment method * Check the final summary before selecting **Deploy** > [!NOTE] > > The deployment order summary is authoritative for current billing options, prices, and discounts. ## View Charges Go to **Billing** > **Invoices** to review invoice history and current statuses. For a billing question or payment issue, create a [support ticket](/account/support-tickets). # Invoices Source: https://docs.arct.cloud/billing/invoices View and download invoices. Go to **Billing** > **Invoices** to see all invoices. ## Invoice Statuses | Status | Meaning | | - | - | | **Paid** | Payment received. | | **Pending** | Awaiting payment. | | **Failed** | Payment failed. Update your [payment method](/billing/payment-methods). | | **Draft** | Being prepared. | | **Refunded** | Payment returned. | ## Download PDF 1. Go to **Billing** > **Invoices** 2. Click on an invoice 3. Click **Download PDF** # Overusage Source: https://docs.arct.cloud/billing/overusage How bandwidth beyond your plan's transfer quota is billed. Each plan includes a monthly outbound transfer quota. See [Virtual Machines](/compute/virtual-machines/overview) for the quota of each plan. ## Bandwidth Overuse Bandwidth overuse is billed at \$0.02 per GB for the Tokyo location. For other locations, the rate is \$0.01 per GB. | Location | Rate | | - | -: | | Amsterdam | \$0.01 per GB | | London | \$0.01 per GB | | Frankfurt | \$0.01 per GB | | Salt Lake City | \$0.01 per GB | | Tokyo | \$0.02 per GB | > [!NOTE] > > Only outbound transfer (egress) counts toward the quota. Inbound transfer (ingress) is free. ## Invoicing Overuse is invoiced monthly. Go to **Billing** > **Invoices** to review your invoices. For a billing question, create a [support ticket](/account/support-tickets). # Payment Methods Source: https://docs.arct.cloud/billing/payment-methods Credit and debit cards, Alipay, cryptocurrency, and ACH direct debit. Arct Cloud accepts credit and debit cards, Alipay, cryptocurrency, and ACH direct debit. The checkout page shows the methods available for your account and order. ## Credit and Debit Cards Visa, Mastercard, American Express, Discover, UnionPay, Diners Club, and JCB cards are accepted, both credit and debit. 1. Go to **Billing** > **Payment Methods** 2. Click **Add Payment Method** 3. Enter your card details ### Cards Issued in India Cards issued in India must be enabled for international transactions before you can pay with them. Cards from Citibank, HDFC Bank, ICICI Bank, Standard Chartered Bank, IndusInd Bank, RBL Bank, Axis Bank, and Kotak Mahindra Bank are less likely to be declined than cards from other banks. ## Alipay Choose Alipay at checkout to pay from your Alipay account. ## Cryptocurrency 1. During deployment or when paying an invoice, select **Cryptocurrency** 2. Follow the checkout instructions to choose a cryptocurrency and complete payment Supported options include Bitcoin (BTC), Ethereum (ETH), Tether (USDT), USD Coin (USDC), Solana (SOL), and many more tokens and networks. Stablecoin payments are accepted from more than 400 wallets. > [!NOTE] > > Cryptocurrency payment is currently limited and may not be available to every customer in every location. The checkout page shows current availability. ## ACH Direct Debit ACH direct debit is available to qualifying customers with a U.S. bank account. ## Manage Payment Methods Go to **Billing** > **Payment Methods** to view saved cards, add new ones, or remove existing ones. The checkout page and order summary show how the selected payment method applies to the current order. # Backups & Snapshots Source: https://docs.arct.cloud/compute/virtual-machines/backups-snapshots Daily backups, manual backups, and snapshots of your server's disk. Backups and snapshots save a copy of your server's disk. Your server stays online while a backup or snapshot is created. | | Backups | Snapshots | | - | - | - | | **Created** | Automatically every day, or manually | Manually | | **Kept** | 7 backup slots. When all are full, the oldest backup is deleted. | Until you delete it | | **Restore this server** | Yes | No | | **Create a new server** | After converting it to a snapshot | Yes, in the same location | | **On server delete** | Deleted | Kept | | **Price** | 20% of the server's plan price | \$0.04 per GB per month | > [!NOTE] > > Backups and snapshots are not available in every location. The order page shows the **Backups** option, and the server page shows the **Backups** tab, where they are available. Snapshots are not available for Windows servers. ## Backups ### Enable Backups * **New server:** select **Add daily backups** on the order page. * **Existing server:** go to **Virtual Machines**, click a server name, open the **Backups** tab, and click **Enable Backups**. The first backup runs within 24 hours. Backups stay on for at least 24 hours. ### Run a Manual Backup 1. Open the server's **Backups** tab 2. Click **Run Manual Backup** 3. Optionally, add a label such as `before-upgrade` 4. Click **Start Backup** A manual backup uses one of the 7 slots. For consistent data, power off your server before you run a manual backup. ### Restore a Backup 1. Open the server's **Backups** tab 2. Open the menu of a backup and click **Restore server** 3. Click **Restore Server** to confirm > [!WARNING] > > Restoring replaces your server's disk with the backup. Changes made since the backup are lost, and the server is offline until the restore finishes. ### Disable Backups 1. Open the server's **Backups** tab 2. Click **Disable Backups** 3. Click **Disable & Delete Backups** to confirm Disabling backups permanently deletes all backups of the server. To keep a backup, [convert it to a snapshot](#convert-a-backup-to-a-snapshot) first. Existing snapshots are kept. ## Snapshots A snapshot is kept until you delete it, even if you delete the server. No backup plan is needed. ### Create a Snapshot 1. Go to **Snapshots** and click **Create Snapshot** 2. Select a server. It must be running or stopped. 3. Optionally, enter a name 4. Click **Create Snapshot** You can also click **Create Snapshot** on a server's **Backups** tab. For consistent data, power off your server first. ### Convert a Backup to a Snapshot 1. Open the server's **Backups** tab 2. Open the menu of a backup and click **Convert to snapshot** 3. Click **Convert to Snapshot** The backup moves to **Snapshots** and no longer counts toward the 7 backup slots. ### Create a Server From a Snapshot 1. Go to **Snapshots** 2. Click **Create New Server** on a snapshot 3. Choose a plan and complete the order The new server is created in the same location as the snapshot. Its plan needs at least as much disk as the snapshot. Your files and apps come with it, and the new server gets a new IP address and new login details. ### Delete a Snapshot Go to **Snapshots** and click **Delete** on the snapshot. A snapshot can't be deleted while an order that uses it is pending. ## Pricing | Item | Price | | - | - | | **Backups** | 20% of the server's plan price, billed with the server | | **Snapshots** | \$0.04 per GB per month, calculated daily from each snapshot's size | # Connect via RDP Source: https://docs.arct.cloud/compute/virtual-machines/connect-rdp Connect to your Windows server using Remote Desktop. Windows Server images are available on plans with 2 or more vCPUs and deploy in 2–4 minutes, depending on the image size. Once the server status is **Running**, connect as `Administrator` over RDP. ## Find Your Server's IP Address Go to **Virtual Machines**, click your server name. The IP address is on the detail page. ## Connect > [tab] Windows > > 1. Press **Windows + R**, type `mstsc`, press **Enter** > 2. Enter your server's IP address > 3. Click **Connect** (accept any certificate warning) > 4. Log in as `Administrator` with the password from server creation > [tab] macOS > > 1. Install [Microsoft Remote Desktop](https://apps.apple.com/app/microsoft-remote-desktop/id1295203466) > 2. Click **+** > **Add PC**, enter your server's IP address > 3. Double-click to connect > 4. Log in as `Administrator` with the password from server creation > [tab] Linux > > 1. Install Remmina: `sudo apt install remmina remmina-plugin-rdp` > 2. Create a new RDP connection with your server's IP address > 3. Log in as `Administrator` with the password from server creation ## Troubleshooting > [accordion] Cannot connect > > * Verify the server status is **Running** > * Verify the IP address is correct > * RDP uses port 3389; make sure it is not blocked by your network > [accordion] Wrong credentials > > Username is `Administrator`. Use the password from server creation. > [accordion] Black screen after connecting > > Disconnect and reconnect, or use the **VNC Console** on the server detail page. # Connect via SSH Source: https://docs.arct.cloud/compute/virtual-machines/connect-ssh Connect to your Linux server using SSH. ## Find Your Server's IP Address Go to **Virtual Machines**, click your server name. The IP address is on the detail page. ## Connect with SSH Key The default username depends on your operating system: | OS | Username | | - | - | | Ubuntu | `ubuntu` | | Debian | `debian` | | CentOS Stream | `cloud-user` | | AlmaLinux | `almalinux` | | Rocky Linux | `rocky` | | Fedora | `fedora` | | Windows | Connect via [RDP](/compute/virtual-machines/connect-rdp) instead | ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP ``` > [!NOTE] > > For Debian servers, use `debian@YOUR_SERVER_IP` instead. If your key is not the default, specify it: ```bash theme={null} ssh -i ~/.ssh/my_key ubuntu@YOUR_SERVER_IP ``` The first time you connect, type `yes` to accept the server fingerprint. ## Connect with Password ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP ``` > [!NOTE] > > For Debian servers, use `debian@YOUR_SERVER_IP` instead. Enter the password provided when the server was created. > [!WARNING] > > Password authentication is less secure than SSH keys. See [SSH Keys](/compute/virtual-machines/ssh-keys). ## Troubleshooting > [accordion] Connection timed out > > * Verify the server status is **Running** in the dashboard > * Verify the IP address is correct > [accordion] Permission denied (publickey) > > * Verify your local key matches the one added to Arct Cloud > * Check key permissions: `chmod 600 ~/.ssh/id_ed25519` > * Specify the key explicitly: `ssh -i ~/.ssh/id_ed25519 ubuntu@YOUR_SERVER_IP` (use `debian@` for Debian servers) > [accordion] Host key verification failed > > This happens after rebuilding a server. Remove the old key: > > ```bash theme={null} > ssh-keygen -R YOUR_SERVER_IP > ``` > [accordion] Cannot connect at all > > Use the **VNC Console** on the server detail page for emergency access. # Deploy a Server Source: https://docs.arct.cloud/compute/virtual-machines/deploy How to deploy a new virtual machine. ## Deployment **1. Open Deployment Page** Open the [new server flow](https://console.arct.cloud/auth/login?screen_hint=signup\&returnTo=/servers/new). After sign-in, the console opens **Create Server**. You can also select **Virtual Machines** in the sidebar and click **Create Server**. **2. Choose a Location** Select a current public deployment location: * **North America:** Salt Lake City * **Europe:** London, Amsterdam, Frankfurt * **Asia Pacific:** Tokyo Availability can change as the platform expands. The deployment UI is authoritative for the tier and location combinations available at order time. **3. Select a Plan** Choose from the Cost Optimized, General Purpose, or High Performance tiers, then select a plan based on your resource needs. See [plans](/compute/virtual-machines/overview) for details. **4. Pick an Operating System** Select an OS image. Linux images are available on every plan. The dashboard offers Windows Server images only when the selected plan has 2 or more vCPUs. Image choices are catalog- and location-driven, so the deployment UI is authoritative. **5. Set Billing Cycle** Choose from the billing options currently shown in the console. Review the period, order total, and any applicable discount. **6. Select SSH Keys** For a Linux server, select one or more SSH keys to install on the server. **7. Set Hostname** Enter a name for your server. **8. Choose Payment Method** * **Credit or debit card** * **Cryptocurrency:** complete checkout with one of the currently supported tokens or networks **9. Deploy** Review the **Order Summary** and click **Deploy**. Linux images deploy in under 30 seconds. Windows Server images deploy in 2–4 minutes, depending on the image size. ## After Deployment 1. Find your server's IP address on the server detail page 2. Connect to a Linux server via [SSH](/compute/virtual-machines/connect-ssh) or a Windows Server via [RDP](/compute/virtual-machines/connect-rdp) # Email Sending & Ports Source: https://docs.arct.cloud/compute/virtual-machines/email-sending-ports Outbound email (SMTP) ports and sending rules. ## Outbound Email (SMTP) Outbound ports 25 and 465 are blocked; port 587 is open. After one paid month, you may submit a support ticket describing your use case for individual review, but approval is not guaranteed. For volume sending, use an email delivery API. # Images Source: https://docs.arct.cloud/compute/virtual-machines/images Operating systems you can deploy, their login users, and where they're offered. ## Available Operating Systems | OS | Versions | Login user | Connect with | | - | - | - | - | | Ubuntu | 22.04 LTS, 24.04 LTS, 26.04 LTS | `ubuntu` | [SSH](/compute/virtual-machines/connect-ssh) | | Debian | 12 (Bookworm), 13 (Trixie) | `debian` | [SSH](/compute/virtual-machines/connect-ssh) | | CentOS Stream | 9, 10 | `cloud-user` | [SSH](/compute/virtual-machines/connect-ssh) | | AlmaLinux | 9, 10 | `almalinux` | [SSH](/compute/virtual-machines/connect-ssh) | | Rocky Linux | 9, 10 | `rocky` | [SSH](/compute/virtual-machines/connect-ssh) | | Fedora | 43, 44 | `fedora` | [SSH](/compute/virtual-machines/connect-ssh) | | Windows Server | 2022 | `Administrator` | [RDP](/compute/virtual-machines/connect-rdp) | > [!NOTE] > > Availability differs per location and plan. **Create Server** shows the images offered for the location and plan you select. ## Choosing an Image * On **Create Server**, pick the location and plan first; the OS list updates to match. * Windows Server needs a plan with 2 or more vCPUs. * Your server page's **How to connect** panel shows the exact username and port. ## Logging In * **Linux:** sign in as the login user above, then use `sudo` for admin tasks. * With an SSH key, sign in with that key. * Without one, the password is in your deploy email. * **Windows:** sign in as `Administrator` with the password from your deploy email. ## Changing the OS Go to your server's **Settings** tab, then **Danger Zone** → **Reinstall Operating System**. Reinstalling erases the disk and installs the image you choose. The images offered are the ones available for the server's location and plan. ## API To list images and their IDs, see [Images in the API Reference](/api-reference/images). # Manage Your Server Source: https://docs.arct.cloud/compute/virtual-machines/manage Start, stop, restart, rebuild, and delete servers. Go to **Virtual Machines** and click a server name to open its detail page. ## Actions | Action | Description | | - | - | | **Start** | Turn on a stopped server. | | **Stop** | Shut down the server. | | **Restart** | Reboot the server. | | **Rebuild** | Open the rebuild flow. Review its current data impact before confirming. | | **Delete** | Open the delete flow. Review its current data and billing impact before confirming. | ## VNC Console Direct browser-based access to your server. Use when SSH/RDP is not working or you're locked out. Available on the server detail page when the server is **Running**. ## Monitoring The server detail page shows CPU, memory, network I/O, and disk I/O metrics. ## Server Statuses | Status | Meaning | | - | - | | **Provisioning** | Server is being set up. Linux images deploy in under 30 seconds; Windows Server images deploy in 2–4 minutes, depending on the image size. | | **Running** | Server is on and accessible. | | **Stopped** | Server is off. | | **Restarting** | Server is rebooting. | | **Error** | Something went wrong. Contact [support](/account/support-tickets). | # Virtual Machines Source: https://docs.arct.cloud/compute/virtual-machines/overview VPS tiers, plan resources, outbound transfer quotas, locations, and operating systems. Arct Cloud offers Cost Optimized, General Purpose, and High Performance VPS plans. Every plan includes NVMe storage, DDoS protection, and network capacity up to 25 Gbps. > [!NOTE] > > Only outbound transfer (egress) counts toward each plan's monthly transfer quota. Inbound transfer (ingress) is free and does not count toward the quota. Transfer beyond the quota is billed as [overusage](/billing/overusage). ## Cost Optimized Cost Optimized plans use AMD EPYC Milan 7003 Series, with speeds up to 3.7 GHz. They are designed for light and variable workloads. | Plan | vCPUs | RAM | NVMe | Outbound transfer | Network | Price/month | | - | -: | -: | -: | -: | - | -: | | **cvm.pico** | 1 | 1 GB | 15 GB | 1 TB | up to 25 Gbps | \$3.89 | | **cvm.nano** | 1 | 2 GB | 25 GB | 2 TB | up to 25 Gbps | \$5.89 | | **cvm.micro** | 2 | 4 GB | 40 GB | 3 TB | up to 25 Gbps | \$8.89 | | **cvm.tiny** | 2 | 6 GB | 55 GB | 4 TB | up to 25 Gbps | \$11.89 | | **cvm.small** | 4 | 8 GB | 75 GB | 5 TB | up to 25 Gbps | \$15.89 | | **cvm.medium** | 4 | 10 GB | 90 GB | 5 TB | up to 25 Gbps | \$18.89 | | **cvm.large** | 6 | 12 GB | 110 GB | 6 TB | up to 25 Gbps | \$24.89 | | **cvm.xlarge** | 8 | 16 GB | 150 GB | 6 TB | up to 25 Gbps | \$31.89 | ## General Purpose General Purpose plans use AMD EPYC Milan 7003 Series, with speeds up to 3.7 GHz. They provide balanced resources for always-on services and cost 30% less than matching High Performance sizes. | Plan | vCPUs | RAM | NVMe | Outbound transfer | Network | Price/month | | - | -: | -: | -: | -: | - | -: | | **vm.nano** | 1 | 2 GB | 25 GB | 5 TB | up to 25 Gbps | \$7.99 | | **vm.micro** | 2 | 4 GB | 40 GB | 5 TB | up to 25 Gbps | \$13.99 | | **vm.tiny** | 4 | 8 GB | 80 GB | 10 TB | up to 25 Gbps | \$24.49 | | **vm.small** | 6 | 12 GB | 120 GB | 10 TB | up to 25 Gbps | \$36.75 | | **vm.medium** | 8 | 16 GB | 160 GB | 10 TB | up to 25 Gbps | \$48.99 | | **vm.large** | 12 | 24 GB | 240 GB | 10 TB | up to 25 Gbps | \$73.50 | | **vm.xlarge** | 16 | 32 GB | 300 GB | 10 TB | up to 25 Gbps | \$97.93 | ## High Performance High Performance plans use AMD Ryzen 9 or AMD EPYC Genoa 9004 Series processors with DDR5 memory for demanding workloads. Ryzen 9 reaches speeds up to 5.7 GHz. | Plan | vCPUs | RAM | NVMe | Outbound transfer | Network | Price/month | | - | -: | -: | -: | -: | - | -: | | **hvm.nano** | 1 | 2 GB | 25 GB | 5 TB | up to 25 Gbps | \$11.99 | | **hvm.micro** | 2 | 4 GB | 40 GB | 5 TB | up to 25 Gbps | \$19.99 | | **hvm.tiny** | 4 | 8 GB | 80 GB | 10 TB | up to 25 Gbps | \$34.99 | | **hvm.small** | 6 | 12 GB | 120 GB | 10 TB | up to 25 Gbps | \$52.50 | | **hvm.medium** | 8 | 16 GB | 160 GB | 10 TB | up to 25 Gbps | \$69.99 | | **hvm.large** | 12 | 24 GB | 240 GB | 10 TB | up to 25 Gbps | \$105.00 | | **hvm.xlarge** | 16 | 32 GB | 300 GB | 10 TB | up to 25 Gbps | \$139.90 | > [!NOTE] > > Prices are listed in USD per month. The deployment UI shows current order totals and the plans and tier/location combinations available at order time. ## Locations Current public deployment locations are: | Location | Region | | - | - | | Amsterdam | Europe | | London | Europe | | Frankfurt | Europe | | Salt Lake City | North America | | Tokyo | Asia Pacific | Location and tier availability can change as the platform expands. Check the deployment UI for the choices available when you create a server. ## Operating Systems * **Linux:** Linux images are available on every plan, deploy in under 30 seconds, and provide root access over SSH. * **Windows:** Windows Server images are available on plans with 2 or more vCPUs, deploy in 2–4 minutes, depending on the image size, and provide administrator access over RDP. Image availability is catalog- and location-driven and can change. The deployment UI shows the current choices for your selected plan and location. See [Images](/compute/virtual-machines/images) for the full list and login users. ## Outbound Email (SMTP) Outbound ports 25 and 465 are blocked; port 587 is open. After one paid month, you may submit a support ticket describing your use case for individual review, but approval is not guaranteed. For volume sending, use an email delivery API. # SSH Keys Source: https://docs.arct.cloud/compute/virtual-machines/ssh-keys Generate and manage SSH keys for server access. ## Generate an SSH Key > [tab] macOS / Linux > > ```bash theme={null} > ssh-keygen -t ed25519 -C "your-email@example.com" > ``` > > Press **Enter** for the default location. Optionally set a passphrase. > > View your public key: > > ```bash theme={null} > cat ~/.ssh/id_ed25519.pub > ``` > [tab] Windows (PowerShell) > > ```powershell theme={null} > ssh-keygen -t ed25519 -C "your-email@example.com" > ``` > > View your public key: > > ```powershell theme={null} > Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub > ``` > [tab] PuTTYgen > > 1. Open PuTTYgen, select **EdDSA** > 2. Click **Generate** > 3. Copy the public key from the text box > 4. Click **Save private key** ## Add a Key to Your Account 1. Go to **Settings** > **SSH Keys** 2. Click **Add SSH Key** 3. Enter a name and paste your public key 4. Click **Add SSH Key** Saved keys can be selected when [deploying a server](/compute/virtual-machines/deploy). ## Remove a Key 1. Go to **Settings** > **SSH Keys** 2. Click the delete icon next to the key 3. Confirm deletion > [!NOTE] > > Removing a key from your account does not remove it from servers that already have it installed. # Quick Start Guide Source: https://docs.arct.cloud/getting-started/quickstart Deploy a server and connect to it. **1. Add a Payment Method (Recommended)** Go to **Billing** > **Payment Methods** to add a credit or debit card. You can also pay with a supported cryptocurrency during deployment. See [Payment Methods](/billing/payment-methods) for every accepted method. **2. Add an SSH Key for Linux** Go to **Settings** > **SSH Keys** and click **Add SSH Key**. If you don't have one, generate it: ```bash theme={null} ssh-keygen -t ed25519 ``` Paste the contents of `~/.ssh/id_ed25519.pub` into the form. **3. Deploy a Server** Open the [new server flow](https://console.arct.cloud/auth/login?screen_hint=signup\&returnTo=/servers/new). After sign-in, the console opens **Create Server**. 1. Choose a currently available location 2. Select a tier and plan 3. Pick an operating system (Linux images are available on every plan; Windows Server images require 2 or more vCPUs) 4. Review the billing options shown in the console 5. For Linux, select your SSH key 6. Set a hostname 7. Choose payment method 8. Click **Deploy** The deployment UI is authoritative for the tier and location combinations currently available. Linux images deploy in under 30 seconds; Windows Server images deploy in 2–4 minutes, depending on the image size. **4. Connect** Once the server status is **Running**, connect to a Linux server via SSH: ```bash theme={null} ssh ubuntu@YOUR_SERVER_IP ``` For Debian servers, use `debian@YOUR_SERVER_IP` instead. For Windows Server, connect over [RDP](/compute/virtual-machines/connect-rdp) as `Administrator`. Find the IP address on your server's detail page in the dashboard. # Arct Cloud Documentation Source: https://docs.arct.cloud/index Arct Cloud platform documentation. ## Getting Started > [card] [Quick Start Guide](/getting-started/quickstart) > > Deploy a server and connect to it. ## Virtual Machines > [card] [Overview](/compute/virtual-machines/overview) > > Plans, outbound transfer quotas, locations, and operating systems. > [card] [Deploy a Server](/compute/virtual-machines/deploy) > > Deploy a new virtual machine. > [card] [Connect via SSH](/compute/virtual-machines/connect-ssh) > > Connect to Linux servers. > [card] [Connect via RDP](/compute/virtual-machines/connect-rdp) > > Connect to Windows servers. > [card] [Manage Your Server](/compute/virtual-machines/manage) > > Start, stop, restart, and delete servers. > [card] [SSH Keys](/compute/virtual-machines/ssh-keys) > > Generate and manage SSH keys. > [card] [Backups & Snapshots](/compute/virtual-machines/backups-snapshots) > > Back up, restore, and snapshot servers. > [card] [Email Sending & Ports](/compute/virtual-machines/email-sending-ports) > > Outbound email (SMTP) ports and sending rules. ## Migrations > [card] [Migration Overview](/migration/overview) > > Move an existing server, site, or database to Arct Cloud. > [card] [Linux Server](/migration/linux-server) > > Copy applications, databases, and services. > [card] [Windows Server](/migration/windows-server) > > Move IIS sites, SQL Server, and scheduled tasks. > [card] [Website and DNS](/migration/website-dns) > > Switch records with minimal downtime. > [card] [WordPress](/migration/wordpress) > > Move a live site onto the Compose stack. ## Apps > [card] [Browse Self-hosted Apps](/apps/overview) > > Deploy automation, monitoring, content, security, data, and AI applications. > [card] [Self-host n8n](/apps/n8n) > > Run workflow automation with persistent data and HTTPS webhooks. > [card] [Self-host Coolify](/apps/coolify) > > Operate a deployment platform on your own Linux server. > [card] [Self-host Uptime Kuma](/apps/uptime-kuma) > > Monitor services and publish a status page. > [card] [Self-host Hermes Agent](/apps/hermes-agent) > > Keep the Hermes messaging gateway running as a service. ## Billing & Payments > [card] [Payment Methods](/billing/payment-methods) > > Cards, Alipay, cryptocurrency, and ACH direct debit. > [card] [Billing Cycles](/billing/billing-cycles) > > Review billing options and order totals. > [card] [Invoices](/billing/invoices) > > View and download invoices. > [card] [Overusage](/billing/overusage) > > Bandwidth beyond your transfer quota. ## Account > [card] [Support Tickets](/account/support-tickets) > > Contact support. > [card] [Activity Logs](/account/activity-logs) > > Account activity history. > [card] [Security](/account/security) > > Account and server security. # Linux Server Migration Source: https://docs.arct.cloud/migration/linux-server Move applications, data, and services from an existing Linux server. This guide copies application data, databases, and service configuration from your current Linux server to an Arct Cloud server. Read the [migration overview](/migration/overview) first. > [!NOTE] > > Copy application data and configuration, not the whole root filesystem. See [why a clean target beats a disk clone](/migration/overview#choose-your-approach). > [!WARNING] > > Stop or pause any service that writes while you copy its data. Anything written after the copy starts is left behind, and the gap is easy to miss until the new server is already live. ## Deploy the Target Server Deploy a Linux server with at least the disk and memory the source server uses. See [Deploy a Server](/compute/virtual-machines/deploy), then [connect over SSH](/compute/virtual-machines/connect-ssh). Match the source distribution and major version where you can. Moving Ubuntu 22.04 to Ubuntu 24.04 works, but expect config changes in nginx, PHP, and systemd unit paths. ## Set Up Access Between Servers Generate a dedicated key on the Arct Cloud server and pull data from the source. Pulling means the source never needs credentials for the new machine. ```bash theme={null} sudo ssh-keygen -t ed25519 -N "" -f /root/.ssh/migration sudo cat /root/.ssh/migration.pub ``` Add that public key to `~/.ssh/authorized_keys` for the root user on the source server, then confirm the connection: ```bash theme={null} sudo ssh -i /root/.ssh/migration root@SOURCE_IP hostname ``` > [!WARNING] > > Delete `/root/.ssh/migration` and remove the key from the source server once the migration is done. ## Capture the System State Application files are the obvious half. The other half is the account, key, and rule state your app depends on. Bundle it on the source server in one pass so nothing is missed: ```bash theme={null} sudo tar -czf /tmp/system-state.tar.gz \ /etc/passwd /etc/group /etc/shadow /etc/gshadow \ /etc/ssh/sshd_config /root/.ssh /home/*/.ssh \ /etc/crontab /etc/cron.d /var/spool/cron ``` Firewall rules are readable rather than file-based, so export them alongside, still on the source server: ```bash theme={null} sudo ufw status numbered > /tmp/ufw-rules.txt ``` Copy both to the new server and unpack the bundle somewhere safe to read from. Do not overwrite the new server's own `/etc/passwd` or `/etc/shadow` with the old ones; use them as the reference when you recreate accounts: ```bash theme={null} sudo scp -i /root/.ssh/migration \ root@SOURCE_IP:/tmp/{system-state.tar.gz,ufw-rules.txt} /tmp/ sudo mkdir -p /tmp/old-state sudo tar -xzf /tmp/system-state.tar.gz -C /tmp/old-state ``` ## Install the Same Packages On the source server, list the packages you installed by hand: ```bash theme={null} apt-mark showmanual > /tmp/packages.list ``` Copy the list over and install it on the Arct Cloud server: ```bash theme={null} sudo scp -i /root/.ssh/migration root@SOURCE_IP:/tmp/packages.list /tmp/ sudo apt-get update xargs -a /tmp/packages.list sudo apt-get install -y ``` On RHEL, AlmaLinux, or Rocky, use `dnf repoquery --userinstalled --qf '%{name}'` and `dnf install`. ## Copy Application Data Use `rsync` for each directory that matters. Run it as often as you like; only changed files transfer. ```bash theme={null} sudo rsync -aAXH --numeric-ids --info=progress2 \ -e "ssh -i /root/.ssh/migration" \ root@SOURCE_IP:/var/www/ /var/www/ ``` | Flag | Why | | - | - | | `-a` | Preserves permissions, timestamps, symlinks | | `-A -X` | Keeps ACLs and extended attributes | | `-H` | Preserves hard links | | `--numeric-ids` | Copies numeric UID and GID instead of remapping by name | Repeat for the rest: `/etc/nginx/`, `/opt/`, `/home/`, `/srv/`, and any application-specific paths. > [!NOTE] > > The trailing slash on the source path matters. `/var/www/` copies the contents; `/var/www` copies the directory itself into the target. ## Move Databases > [!WARNING] > > Never `rsync` a running database's data directory. Dump it instead, or stop the database first. > [accordion] MySQL or MariaDB > > On the source server: > > ```bash theme={null} > mysqldump --single-transaction --routines --triggers \ > --all-databases > /tmp/mysql-dump.sql > ``` > > On the Arct Cloud server: > > ```bash theme={null} > sudo scp -i /root/.ssh/migration root@SOURCE_IP:/tmp/mysql-dump.sql /tmp/ > sudo mysql < /tmp/mysql-dump.sql > sudo systemctl restart mysql > ``` > > Application users and grants come across with `--all-databases`. Verify with `SHOW GRANTS FOR 'appuser'@'localhost';`. > [accordion] PostgreSQL > > On the source server: > > ```bash theme={null} > sudo -u postgres pg_dumpall > /tmp/pg-dump.sql > ``` > > On the Arct Cloud server: > > ```bash theme={null} > sudo scp -i /root/.ssh/migration root@SOURCE_IP:/tmp/pg-dump.sql /tmp/ > sudo -u postgres psql -f /tmp/pg-dump.sql postgres > ``` > > `pg_dumpall` includes roles and passwords. Match the major PostgreSQL version on both sides. > [accordion] MongoDB > > ```bash theme={null} > mongodump --out /tmp/mongo-dump > ``` > > Copy the directory across, then restore: > > ```bash theme={null} > mongorestore /tmp/mongo-dump > ``` > [accordion] Redis > > Trigger a save on the source, copy `/var/lib/redis/dump.rdb` while Redis is stopped on the target, then start it: > > ```bash theme={null} > redis-cli SAVE > ``` ## Recreate Services and Schedules Copy your unit files, then reload: ```bash theme={null} sudo rsync -a -e "ssh -i /root/.ssh/migration" \ root@SOURCE_IP:/etc/systemd/system/ /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now your-service ``` Recreate local users with the same UID before copying files they own. Read the original UID out of the captured `/tmp/old-state/etc/passwd`: ```bash theme={null} sudo useradd -u 1001 -m -s /bin/bash appuser ``` Restore each user's crontab from the captured state, then check `/tmp/old-state/etc/cron.d` for system-level jobs: ```bash theme={null} sudo crontab -u appuser /tmp/old-state/var/spool/cron/crontabs/appuser ``` ## Reapply the Firewall Read the rules you exported to `/tmp/ufw-rules.txt`, then recreate them: ```bash theme={null} sudo ufw allow OpenSSH sudo ufw allow 80,443/tcp sudo ufw enable ``` On `firewalld`, use `firewall-cmd --list-all` and `firewall-cmd --permanent --add-service=`. ## Verify Before DNS Point your own machine at the new server without touching public DNS. Add a line to your local hosts file, `/etc/hosts` on Linux and macOS or `C:\Windows\System32\drivers\etc\hosts` on Windows: ``` NEW_SERVER_IP example.com www.example.com ``` Load the site, sign in, submit a form, and check the logs: ```bash theme={null} sudo journalctl -u your-service -n 100 --no-pager ``` Remove the hosts entry when you are done testing. ## Cut Over **1. Stop Writes on the Source** Put the application in maintenance mode or stop its service so no new data lands on the old server. **2. Run a Final Sync** Repeat the `rsync` commands and re-dump the database. This pass is fast because only recent changes transfer. **3. Update DNS** Change the A and AAAA records to the new IP. See [Website and DNS Migration](/migration/website-dns) for record-level detail. **4. Watch the New Server** Follow the logs and the CPU, memory, and network graphs on the server detail page for the first hour. **5. Decommission the Source** Keep the old server for a few days, then run the [checks before you delete it](/migration/overview#before-you-delete-the-old-server). ## Troubleshooting > [accordion] Permission denied (publickey) when pulling from the source > > Confirm the public key is in the source's `/root/.ssh/authorized_keys`, that the file is `chmod 600`, and that `PermitRootLogin` allows key auth in the source's `/etc/ssh/sshd_config`. > [accordion] Files arrive owned by the wrong user > > You omitted `--numeric-ids`, so rsync remapped ownership by name. Recreate the users with matching UIDs, then re-run the sync with the flag. > [accordion] The application starts but cannot reach its database > > Check the connection host in your app config. `localhost` on the old server may have meant a socket path that differs on the new distribution version. Confirm the database is listening with `ss -lntp`. > [accordion] rsync fails with 'No space left on device' > > Run `df -h` on the target. If the plan disk is smaller than the source's used space, resize before continuing. > [accordion] SELinux blocks the web server after copying files > > On RHEL-family systems, restore the file contexts: `sudo restorecon -Rv /var/www`. # Migration Overview Source: https://docs.arct.cloud/migration/overview Move an existing server, site, or database to Arct Cloud. Migrating means copying your data and configuration onto a new Arct Cloud server, verifying it works, then pointing DNS at it. Your current server keeps running the whole time, so you control the switch. ## Choose Your Approach Deploy a clean Arct Cloud image, install your software stack, and move your data and configuration onto it. That is the approach every guide here follows. The alternative, cloning your old server's disk image onto the new one, carries the old kernel, storage drivers, and network configuration with it. Those are matched to the hardware and virtualization of the provider you are leaving, so a cloned system often fails to boot or comes up without networking. Diagnosing that means working inside a system neither you nor our engineers have a clean reference for. > [!NOTE] > > If you need the old machine's exact partition layout, take a full backup and keep the source server running until the new one is verified. A clean image plus your data is faster to recover than a broken clone. ## Pick Your Guide | You are moving | Guide | | - | - | | A Linux server: apps, databases, services | [Linux Server Migration](/migration/linux-server) | | A Windows Server: IIS, SQL Server, scheduled tasks | [Windows Server Migration](/migration/windows-server) | | A website and its DNS records | [Website and DNS Migration](/migration/website-dns) | | A WordPress site | [WordPress Migration](/migration/wordpress) | ## Before You Start **1. Inventory the Source Server** List what actually has to move: application directories, databases, service configs, cron jobs, firewall rules, TLS certificates, and any credentials stored on disk. **2. Check Disk and Memory** Run `df -h` and `free -m` on the source server. Pick an Arct Cloud [plan](/compute/virtual-machines/overview) that matches or exceeds current usage. **3. Pick a Location by Latency** Measure the round trip from where your users and upstream services actually are, then choose the closest available location. The deployment flow shows which locations are currently available. **4. Lower Your DNS TTL** At least 24 hours before cutover, set the TTL on the records you will change to 300 seconds. Traffic then moves within minutes instead of hours. **5. Add an SSH Key** Go to **Settings** > **SSH Keys** and add your public key. See [SSH Keys](/compute/virtual-machines/ssh-keys). **6. Take a Backup** Back up the source server before you touch anything, and keep the backup off both machines. ## Cutover Order 1. Deploy the Arct Cloud server and install the same software stack. 2. Copy data and configuration. 3. Verify the new server using a local hosts file entry, before any DNS change. 4. Stop writes on the source, run a final sync, then update DNS. 5. Keep the source server running for a few days, then decommission it. > [!WARNING] > > Do not change DNS before step 3 passes. A verified server behind a stale record is recoverable; an unverified one is downtime. ## Before You Delete the Old Server Time alone is not the signal. Check that nothing still depends on it: * Watch its access and application logs. Requests still arriving mean a record, a hardcoded IP, or a cron job somewhere still points at it. * Run `ss -tnp` on it to see which connections are still open and what is holding them. * Confirm your own services reference the new host. Application configs, API callbacks, monitoring checks, and backup jobs often carry the old IP. * Check that scheduled jobs run on the new server and not on both. When the logs are quiet and nothing references the old IP, take a final backup and shut it down. ## Getting Help Open a [support ticket](/account/support-tickets) if you get stuck. Tickets are handled by infrastructure engineers, and the same engineer stays on the thread until it is closed. They can read your server logs to help with migration and setup. # Website and DNS Migration Source: https://docs.arct.cloud/migration/website-dns Move a website and switch its DNS records with minimal downtime. This guide covers the DNS side of a migration: what to change, what to leave alone, and the order that keeps the site reachable throughout. Move the files and database first with the [Linux](/migration/linux-server) or [Windows](/migration/windows-server) guide. ## Inventory Your Records Before you change anything, export the current zone from your DNS provider or read it back: ```bash theme={null} dig example.com ANY +noall +answer dig www.example.com A +short dig example.com MX +short dig example.com TXT +short ``` | Record | Change it? | | - | - | | `A`, `AAAA` for the site | Yes. Point to the new server IP. | | `CNAME` for `www` | Usually no, if it already points at the apex. | | `MX` | Only if mail moves too. | | `TXT` for SPF, DKIM, DMARC | Only if mail moves too. | | `CAA` | Only if your certificate issuer changes. | > [!WARNING] > > Changing `MX` or SPF records while only the website moves will break mail delivery. Leave mail records alone unless mail is part of the migration. ## Lower the TTL First At least 24 hours before cutover, set the TTL on the records you plan to change to 300 seconds. Resolvers cache the old value for the length of the old TTL, so this step has to happen before, not during, the switch. ```bash theme={null} dig example.com A +noall +answer ``` The number in the second column is the remaining cache lifetime. Wait for it to drop to the new value before you continue. ## Configure the Web Server Recreate the site config on the Arct Cloud server. > [accordion] nginx > > ```nginx theme={null} > server { > listen 80; > listen [::]:80; > server_name example.com www.example.com; > root /var/www/example.com; > index index.php index.html; > } > ``` > > ```bash theme={null} > sudo nginx -t && sudo systemctl reload nginx > ``` > [accordion] Apache > > ```apache theme={null} > > ServerName example.com > ServerAlias www.example.com > DocumentRoot /var/www/example.com > > ``` > > ```bash theme={null} > sudo apachectl configtest && sudo systemctl reload apache2 > ``` ## Handle TLS Certificates Issue the certificate before the DNS change so there is no gap where the site answers on HTTP only. Copy the existing Let's Encrypt state from the source server: ```bash theme={null} sudo rsync -aAX -e "ssh -i /root/.ssh/migration" \ root@SOURCE_IP:/etc/letsencrypt/ /etc/letsencrypt/ ``` Install certbot on the new server and let it wire up the web server config: ```bash theme={null} sudo apt-get install -y certbot python3-certbot-nginx sudo certbot --nginx -d example.com -d www.example.com ``` After DNS points at the new server, force a renewal so the certificate is issued and validated from here: ```bash theme={null} sudo certbot renew --force-renewal sudo systemctl status certbot.timer ``` > [!NOTE] > > HTTP-01 validation requires DNS to already resolve to the server being validated. To issue a fresh certificate before cutover, use DNS-01 validation instead. ## Verify Before You Switch Point your own machine at the new server with a local hosts file entry, `/etc/hosts` on Linux and macOS or `C:\Windows\System32\drivers\etc\hosts` on Windows: ``` NEW_SERVER_IP example.com www.example.com ``` Then check: * The homepage and two or three deep pages load * Sign-in works and sessions persist * A form submission writes to the database * Uploads and media resolve * HTTPS shows a valid certificate * Redirects, including apex to `www` or the reverse, still fire Remove the hosts entry afterward. ## Cut Over **1. Freeze the Source** Put the site into maintenance mode so no new orders, posts, or uploads land on the old server. **2. Run a Final Sync** Copy files and re-import the database one last time. **3. Update the A and AAAA Records** Change them to the new server IP at your DNS provider. With a 300 second TTL, most resolvers pick up the change within five minutes. **4. Confirm Propagation** ```bash theme={null} dig example.com A +short @8.8.8.8 dig example.com A +short @1.1.1.1 ``` Both should return the new IP. **5. Restore the TTL** Set the TTL back to 3600 seconds or your usual value once traffic has moved. **6. Keep the Source Running** Leave the old server up for a few days. Stragglers on cached DNS will still reach it, and you keep a rollback path. Before deleting it, run the [checks before you delete it](/migration/overview#before-you-delete-the-old-server). ## Troubleshooting > [accordion] Some visitors still land on the old server > > Their resolver cached the record before you lowered the TTL. It clears on its own. Leaving the source server running in maintenance mode avoids errors during the tail. > [accordion] The browser shows a certificate warning > > The certificate covers a name the request did not use, or certbot wrote its config after the last reload. Check with `sudo certbot certificates`, then reload the web server. > [accordion] Mail stopped after the move > > An `MX` or SPF record was changed along with the site records. Restore them to their previous values, then confirm with `dig example.com MX +short` and `dig example.com TXT +short`. > [accordion] The site loads but images and CSS are missing > > Absolute URLs in the database or config still reference the old host or an old path. Search the database for the old domain and update it. > [accordion] Mixed content warnings on HTTPS > > The site config still generates `http://` URLs. Update the site URL setting and add a redirect from HTTP to HTTPS in the web server config. # Windows Server Migration Source: https://docs.arct.cloud/migration/windows-server Move IIS sites, SQL Server databases, and scheduled tasks to a Windows Server. This guide moves data, roles, and configuration from an existing Windows Server to an Arct Cloud Windows Server. Read the [migration overview](/migration/overview) first. > [!NOTE] > > Windows Server images are offered on plans with 2 or more vCPUs. Windows images deploy in 2 to 4 minutes, depending on the image size. > [!WARNING] > > Stop or pause any service that writes while you copy its data. Anything written after the copy starts is left behind. See [why a clean target beats a disk clone](/migration/overview#choose-your-approach). ## Deploy the Target Server Deploy a Windows Server image on a plan with at least the disk and memory the source uses. See [Deploy a Server](/compute/virtual-machines/deploy), then [connect over RDP](/compute/virtual-machines/connect-rdp) as `Administrator`. ## Install Roles and Features First Export the source server's role list in PowerShell: ```powershell theme={null} Get-WindowsFeature | Where-Object InstallState -eq Installed | Select-Object -ExpandProperty Name > C:\features.txt ``` Install the ones you need on the Arct Cloud server: ```powershell theme={null} Install-WindowsFeature Web-Server, Web-Asp-Net45 -IncludeManagementTools ``` Reboot if the installer asks for it, before you copy any data. ## Transfer Files > [!WARNING] > > Do not expose SMB (port 445) to the public internet to run a file copy. Transfer over SSH or through storage you already trust. Compress the data on the source, then pull it over SSH. The OpenSSH client ships with Windows Server 2019 and later: ```powershell theme={null} Compress-Archive -Path C:\inetpub\wwwroot -DestinationPath C:\wwwroot.zip ``` From the Arct Cloud server: ```powershell theme={null} scp Administrator@SOURCE_IP:C:/wwwroot.zip C:\ Expand-Archive -Path C:\wwwroot.zip -DestinationPath C:\inetpub\ -Force ``` If both servers sit on a private network or VPN, `robocopy` is faster for repeat syncs and preserves ACLs: ```powershell theme={null} robocopy \\SOURCE_HOST\c$\inetpub\wwwroot C:\inetpub\wwwroot /MIR /COPYALL /R:2 /W:5 /LOG:C:\copy.log ``` > [!WARNING] > > `/MIR` deletes files in the destination that no longer exist in the source. Confirm the destination path before running it. ## Move IIS Sites Export the site configuration on the source: ```powershell theme={null} & $env:windir\system32\inetsrv\appcmd.exe list site /config /xml > C:\sites.xml & $env:windir\system32\inetsrv\appcmd.exe list apppool /config /xml > C:\apppools.xml ``` Copy both files across, then import them in this order: ```powershell theme={null} & $env:windir\system32\inetsrv\appcmd.exe add apppool /in < C:\apppools.xml & $env:windir\system32\inetsrv\appcmd.exe add site /in < C:\sites.xml ``` Application pool identities do not carry passwords across. Reset them under **IIS Manager** > **Application Pools** > **Advanced Settings**. ## Move SQL Server Databases Back up each database on the source: ```sql theme={null} BACKUP DATABASE [AppDb] TO DISK = 'C:\backup\AppDb.bak' WITH COMPRESSION, INIT; ``` Copy the `.bak` file to the Arct Cloud server and restore it: ```sql theme={null} RESTORE DATABASE [AppDb] FROM DISK = 'C:\backup\AppDb.bak' WITH MOVE 'AppDb' TO 'C:\Data\AppDb.mdf', MOVE 'AppDb_log' TO 'C:\Data\AppDb_log.ldf', REPLACE; ``` SQL logins are stored on the instance, not in the database, so recreate them and repair the orphaned users: ```sql theme={null} ALTER USER [appuser] WITH LOGIN = [appuser]; ``` Restore to the same SQL Server major version or newer. A backup cannot be restored to an older version. ## Scheduled Tasks, Users, and Firewall Export a scheduled task on the source and recreate it on the target: ```powershell theme={null} schtasks /query /tn "NightlyJob" /xml > C:\NightlyJob.xml ``` ```powershell theme={null} schtasks /create /tn "NightlyJob" /xml C:\NightlyJob.xml /ru "DOMAIN\user" /rp ``` Export the firewall policy and import it on the new server: ```powershell theme={null} netsh advfirewall export "C:\firewall.wfw" ``` ```powershell theme={null} netsh advfirewall import "C:\firewall.wfw" ``` Recreate local users and group memberships by hand. Local account passwords do not transfer. ## Verify Before DNS Add an entry to `C:\Windows\System32\drivers\etc\hosts` on your own machine, opened in an elevated editor: ``` NEW_SERVER_IP example.com www.example.com ``` Browse the site, sign in, and check **Event Viewer** > **Windows Logs** > **Application** for errors. Remove the entry after testing. ## Cut Over **1. Stop Writes on the Source** Stop the site in IIS Manager so no new data lands on the old server. **2. Run a Final Copy** Repeat the file transfer and take a fresh database backup and restore. **3. Update DNS** Change the A and AAAA records to the new IP. See [Website and DNS Migration](/migration/website-dns). **4. Watch the New Server** Follow Event Viewer and the metrics on the server detail page for the first hour. **5. Decommission the Source** Keep the old server for a few days, then run the [checks before you delete it](/migration/overview#before-you-delete-the-old-server). ## Troubleshooting > [accordion] The site returns HTTP 503 > > The application pool stopped. Open **IIS Manager** > **Application Pools** and check the identity credentials, which do not survive an `appcmd` import. > [accordion] SQL Server login fails after restore > > The database user is orphaned from its instance login. Run `ALTER USER [name] WITH LOGIN = [name];` against the restored database. > [accordion] RDP will not connect > > Confirm the server status is **Running**, then use the **VNC Console** on the server detail page to check that Remote Desktop and the firewall rule are enabled. See [Connect via RDP](/compute/virtual-machines/connect-rdp). > [accordion] robocopy reports access denied on every file > > `/COPYALL` needs backup privileges. Run the shell as Administrator, or drop to `/COPY:DAT` if you do not need to preserve auditing and ownership data. > [accordion] A scheduled task never runs > > The task was imported without stored credentials. Recreate it with `/ru` and `/rp` so the password is set on the new server. # WordPress Migration Source: https://docs.arct.cloud/migration/wordpress Move an existing WordPress site onto an Arct Cloud server. This guide moves a live WordPress site onto the Compose stack from [Self-host WordPress on a VPS](/apps/wordpress). Read the [migration overview](/migration/overview) first. You need two things from the old host: the WordPress files under the document root, and a dump of the database. Everything else is rebuilt on the new server. > [!NOTE] > > Arct Cloud provides the unmanaged Linux VPS. WordPress administration, plugins, themes, and updates remain yours. Arct Cloud does not provide WordPress application support. ## Export from the Old Host **1. Put the Site in Maintenance Mode** Anything a visitor writes after you take the dump is lost. Enable maintenance mode, or take the export during your quietest hour and repeat it at cutover. **2. Dump the Database** Read the database name, user, and password out of `wp-config.php`, then: ```bash theme={null} mysqldump --single-transaction --quick --no-tablespaces \ -u WP_DB_USER -p WP_DB_NAME > ~/wordpress-db.sql ``` On shared hosting without shell access, export the database from phpMyAdmin instead: select the database, choose **Export**, keep the **Quick** method and **SQL** format. **3. Archive the Files** From the document root: ```bash theme={null} tar -czf ~/wordpress-files.tar.gz -C /path/to/public_html . ``` The archive must contain `wp-content/` in full. Core files are replaced by the container image, but your uploads, themes, plugins, and any `mu-plugins` live only here. **4. Note the Site URL** ```bash theme={null} grep -E "siteurl|home" ~/wordpress-db.sql | head ``` Write down the exact scheme and host currently stored. You need it in the search and replace step below. ## Stand Up the Target Stack Follow [Self-host WordPress on a VPS](/apps/wordpress) through **Start the Stack**, with two changes: 1. **Do not complete the WordPress installer.** You are importing a database, so a fresh install would be overwritten anyway. 2. **Stage the site with an internal certificate.** DNS still points at the old host, so Caddy cannot complete an ACME challenge for your domain yet. Add `tls internal` to the site block in `/opt/wordpress/Caddyfile`: ```caddy Caddyfile theme={null} www.example.com { tls internal basic_auth { setup REPLACE_WITH_HASH } encode zstd gzip reverse_proxy wordpress:80 } ``` Caddy then issues a certificate from its own local authority. Your browser will warn that it is untrusted, which is expected while staging. You remove the line after cutover. ## Add a WP-CLI Service The search and replace step needs WP-CLI against the same volume and database. Add this service to `/opt/wordpress/compose.yaml`, alongside the existing ones: ```yaml compose.yaml theme={null} wpcli: image: wordpress:cli-php8.3 profiles: ["tools"] depends_on: - db user: "33:33" environment: WORDPRESS_DB_HOST: db:3306 WORDPRESS_DB_USER: wordpress WORDPRESS_DB_NAME: wordpress WORDPRESS_DB_PASSWORD_FILE: /run/secrets/db_password secrets: - db_password volumes: - wordpress_data:/var/www/html ``` The `tools` profile keeps it out of `docker compose up`. It runs only when you ask for it by name. ## Import **1. Copy the Export Across** From the Arct Cloud server: ```bash theme={null} scp OLD_USER@SOURCE_IP:~/wordpress-db.sql ~/ scp OLD_USER@SOURCE_IP:~/wordpress-files.tar.gz ~/ ``` **2. Restore wp-content** Unpack only `wp-content` into the running container. Core files come from the image and should not be overwritten by the old host's copies: ```bash theme={null} cd /opt/wordpress sudo tar -xzf ~/wordpress-files.tar.gz -C /tmp ./wp-content sudo docker compose cp /tmp/wp-content wordpress:/var/www/html/ sudo docker compose exec wordpress chown -R www-data:www-data /var/www/html/wp-content ``` **3. Import the Database** ```bash theme={null} cd /opt/wordpress sudo docker compose exec -T db sh -c \ 'exec mysql -uwordpress -p"$(cat /run/secrets/db_password)" wordpress' < ~/wordpress-db.sql ``` The dump carries its own table prefix. If the old site used a prefix other than `wp_`, add the matching `$table_prefix` line to the WordPress config through `WORDPRESS_CONFIG_EXTRA` in `compose.yaml`, then recreate the container. **4. Update the Site URL** Only if the domain or scheme changed. Serialized values are stored with byte-length prefixes, so a plain `sed` over the dump corrupts widget and plugin settings. WP-CLI rewrites them correctly: ```bash theme={null} cd /opt/wordpress sudo docker compose run --rm wpcli wp search-replace \ 'http://old.example.com' 'https://www.example.com' \ --skip-columns=guid --report-changed-only ``` Leave `guid` alone. Feed readers key off it, and rewriting it makes every post look new. **5. Flush Permalinks and Caches** ```bash theme={null} cd /opt/wordpress sudo docker compose run --rm wpcli wp rewrite flush sudo docker compose run --rm wpcli wp cache flush ``` ## Verify Before DNS Add the new server's IP to your own machine's hosts file, `/etc/hosts` on Linux and macOS or `C:\Windows\System32\drivers\etc\hosts` on Windows: ``` NEW_SERVER_IP www.example.com ``` Load the site, accept the staging certificate warning, and clear the temporary Basic Authentication prompt. Then check: * The homepage, a post, a category archive, and a page all load * Media in `wp-content/uploads` resolves rather than 404s * The admin dashboard signs in and **Settings** shows the expected site address * Permalinks work on a deep URL, not only the homepage * Contact forms, search, and any commerce checkout still function * **Tools** > **Site Health** reports no new critical issues Remove the hosts entry when you are done. ## Cut Over **1. Take a Final Export** Repeat the database dump and the `wp-content` archive from the old host, then re-import. Comments, orders, and posts written since your first export live only there. **2. Update DNS** Point the `A` and `AAAA` records at the new server. See [Website and DNS Migration](/migration/website-dns) for TTL handling and propagation checks. **3. Issue the Real Certificate** Once DNS resolves to the new server, remove both `tls internal` and the `basic_auth` block from `/opt/wordpress/Caddyfile`, then reload: ```bash theme={null} cd /opt/wordpress sudo docker compose exec caddy caddy validate --config /etc/caddy/Caddyfile sudo docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile curl -fsSI https://www.example.com ``` Caddy completes the ACME challenge and replaces the staging certificate. **4. Set Up Backups** Follow **Back Up and Restore** in the [WordPress deployment guide](/apps/wordpress). The old host's backup schedule does not follow the site. **5. Decommission the Old Host** Keep it for a few days, then run the [checks before you delete it](/migration/overview#before-you-delete-the-old-server). ## Troubleshooting > [accordion] Error establishing a database connection > > The import ran but the table prefix does not match. Check with `sudo docker compose run --rm wpcli wp db tables`, then set `$table_prefix` through `WORDPRESS_CONFIG_EXTRA` to match what the dump created. > [accordion] The site redirects to the old domain > > `siteurl` and `home` still hold the old value. Confirm with `wp option get siteurl`, then re-run the search and replace step. > [accordion] Homepage loads but every other URL returns 404 > > Permalink rules were not rebuilt. Run `wp rewrite flush`. The Compose stack proxies through Caddy to Apache, so `.htaccess` from the old host still applies inside the container. > [accordion] Images are missing or uploads fail > > File ownership did not survive the copy. Re-run `chown -R www-data:www-data /var/www/html/wp-content` inside the WordPress container, then check free disk space with `df -h`. > [accordion] A caching or security plugin breaks the site after import > > Plugins that write server-level config expect the old host's stack. Disable them with `wp plugin deactivate PLUGIN_NAME`, load the site, then reconfigure them for a containerized Apache behind a reverse proxy. > [accordion] Mixed content warnings after moving to HTTPS > > The old site stored `http://` URLs in post content. Re-run the search and replace with the `http://` to `https://` pair for the same host.