Skip to content
GuideForOperatorWith or without Foxden Admin

Install Foxden ​

This page takes you from an empty Linux server to your first sign-in as the Owner, with the foxden command-line tool.

Before you start ​

  • A server that meets Plan your server, with its public IP address.
  • A domain you control, and an A record for *.your-domain pointing at the server. For Arctic on its own, a record for the one name it will use.
  • An email address you read. You become the Owner, and it is the contact for the certificates.
  • Optional, and fine to add later in Admin: a Resend account for email, a Google or Microsoft client for sign-in, and an AI provider key.

The installer needs a public release

The installer downloads the foxden tool from Foxden's public releases, and the apps pull their images from the public registry. Until the first public release is published, the installer stops with has no public foxden release yet and says you need an install code (FOXDEN_INSTALL_CODE), and the app images need a registry username and pull token. Only Codefox gives out install codes and pull tokens. With a code, run the installer as FOXDEN_INSTALL_CODE=<code> bash -c "$(curl -fsSL https://admin.codefox.ai/cli)", and give the registry login when foxden init asks for it.

Get the foxden tool ​

Install it on the computer you work from (Linux or macOS, Intel or ARM), or on the server itself.

  1. Run the installer:

    bash
    curl -fsSL https://admin.codefox.ai/cli | bash

    It downloads the newest release, checks its SHA-256 checksum (and its signature when cosign is installed), prints the checked digest, and puts foxden in /usr/local/bin. It asks for your password when that folder needs sudo. It does not start an install.

  2. Check it: foxden --version.

To read the installer before you run it, download it with curl -fsSL https://admin.codefox.ai/cli -o install.sh, read it, then run bash install.sh.

Point foxden at the server ​

Pick one way.

  • From your computer. Run foxden connect root@203.0.113.7, with your server's user and address. The first time, foxden shows the server's SSH fingerprint and asks you to trust it. The user must be root or have passwordless sudo, and SSH must use a key. Every server command after this runs on that server over SSH.
  • On the server. Sign in to the server over SSH and run the commands there as root. When you run foxden init, it asks This looks like a server (...). Install here? Answer yes. If it does not ask and says no server is connected, run it as sudo FOXDEN_LOCAL=1 foxden init.

Install ​

  1. Run foxden init.

    foxden checks the server before it asks anything: root access, the operating system, the processor, that ports 80 and 443 are free, the size, that ghcr.io can be reached, and the Docker version. A server that fails a check costs you no answers; the message says what to fix. See Fix server problems.

  2. At Which products go on this box?, select each app you want with the space bar. Each row says whether it fits on this server. Admin is added for you when you pick two or more, or one app other than Arctic.

  3. Press Enter.

  4. Type your domain at the web address question, for example example.com. Each app gets its own name under it.

    If the DNS record is missing, foxden shows the exact record to make and asks DNS is not ready. What now?: wait (it checks every 10 seconds for up to 10 minutes), continue anyway, or quit. After quitting, run foxden init --resume once the record is live.

  5. Type your email address. It becomes the Owner's address and the certificate contact. Without Admin, foxden also asks for your organisation's name.

  6. Answer the question that starts Add ... now? Not needed to start. Answer no to install now and set these up later in Admin. Answer yes to give them now: how people sign in (email link, Google, Microsoft, or decide later in Admin), the Resend sender and key, the Google or Microsoft client, the AI key, the registry login, and an off-site backup destination. Secrets are typed at a hidden prompt.

  7. Read the plan foxden shows. Nothing has been written yet.

  8. Answer yes at Apply this plan to ...?

    foxden then works through the plan and shows each step: the firewall (it allows SSH, 80 and 443, and refuses rather than lock you out when it cannot tell your SSH port), system packages, Docker when it is missing, log size limits, each app's files and .env with its secrets made fresh, nightly backups with their passphrase file, the images, the databases, each app started and checked, then the shared web server and the links between apps. The first install takes several minutes, most of it downloading images.

If a step fails, fix what the message names and run foxden init --resume. It skips the steps already done. It asks again for any secret you typed, because it never saves secrets in its progress file.

Read the hand-over screen ​

When the install finishes, foxden prints what you need next. Keep a copy of it.

  • Open this link to finish setting up: a one-time link into Admin. Keep it private: it works until someone has signed in another way. foxden console link prints it again.
  • Each app's address, and whether it answered over HTTPS. A certificate can take about 30 seconds after the first visit; reload once before you worry.
  • These cannot be recovered if the box is lost. Escrow them today: the secrets in each app's .env and each backup passphrase file. Copy them into your password manager now. See Keys, secrets and access.
  • Backups: when each app is backed up each night, and whether an off-site copy is set up.
  • Mail is off: the apps that will not send email until you set it up. See Set up outgoing email.
  • Updates: which apps update themselves.

Sign in for the first time ​

  1. Open the setup link from the hand-over screen. It signs you in to Admin as the Owner.
  2. Carry on with your first day as Owner: name the company, set up sign-in for your people and give them access.

An app installed without Admin gets its own setup link instead, which creates that app's first account: Arctic, Corsac, Pampas, Cape and Library print it, and for Fennec the screen says where to find it. See the app's page under Self-host.

Add an app later ​

In Admin:

  1. Open Server › Products.
  2. Select Add a product. Apps the server has no room for are listed with the reason.
  3. Select Add beside the app.
  4. Select Add and the app's name, for example Add Corsac. The server installs it and connects it to Admin and the other apps. This takes a few minutes, and Admin restarts once on the way.
  5. Give people access to it on People. Until you do, nobody can open it.

With the CLI: run foxden init --products <app>, for example foxden init --products corsac. With Admin on the server, the new app is connected to it. The hand-over screen then says Give the new products out: give people access on People in Admin.

Install without questions ​

For a script, give every answer as a flag and add --yes:

bash
foxden init --non-interactive --products fennec,corsac --domain example.com --admin-email you@example.com --yes

Each question has a flag and a FOXDEN_* variable; a secret's flag names a file (--resend-api-key-file), never the value. A missing answer is reported with the flag and variable for each. foxden list <app> prints the full line for one app, and --dry-run shows the plan without changing anything. See foxden in scripts and agents.

There is no uninstall ​

foxden installs and adds apps, but has no command that removes one.

Foxden is open source under Apache-2.0.