import CodeBlock from '@theme/CodeBlock';
import WgetQuickInstaller from "@site/src/components/WgetQuickInstaller";

# Install

## Prerequisites

-   A Linux system with root access and a public IP address
    -   We recommend Ubuntu or Debian based systems
-   [A domain name pointed to your server's IP address](./02-dns-networking.md)
-   [TCP ports 80, 443, and UDP port 51820 exposed to your Linux instance.](./02-dns-networking.md)
    -   **Note:** Docker’s NAT-based port publishing feature automatically exposes all ports defined in `docker-compose` file. This behavior can bypass your host firewall settings, potentially exposing services that you did not intend to make public. It is important to review and manage these port configurations to minimize security risks.
-   An email address for Let's Encrypt certificate registration
-   (Optionally) a SMTP server

## Using a VPS

If you need a VPS to run Pangolin, [RackNerd](https://my.racknerd.com/aff.php?aff=13788) is a great option, and often has generous promotions. More options can be found in our [VPS guide](./01-choosing-a-vps.md).

A good option is [**1 vCPU, 1GB RAM less than $1 a month**](https://my.racknerd.com/aff.php?aff=13788&pid=903).

## Installation Steps

We also have a short and quick [YouTube video](https://youtu.be/W0uVLjTyAn8) showing the install process!

### 1. Downloading and Running the Installer

:::tip

The installer will place all files in the current directory. If you want to install Pangolin in a different directory, you can move the installer to that directory and run it there.

:::

Installer binaries for Linux can be found in the [Github releases](https://github.com/fosrl/pangolin/releases) for ARM and AMD64 (x86_64).

<WgetQuickInstaller />

The downloaded files will be named `installer` in the current directory.

The installer must be run as root. If you're not already root, switch to the root user or use sudo:

```bash
sudo ./installer
```

### 2. Basic Configuration

The installer will prompt you for the following basic information. For example:

1. **Base Domain Name**: Enter your base fully qualified domain name (without any subdomains) Example: `example.com`
2. **Dashboard Domain Name**: The domain where the application will be hosted. This is used for many things, including generating links. You can run Pangolin on a subdomain or root domain. Example: `pangolin.example.com`
3. **Let's Encrypt Email**: Provide an email address for SSL certificate registration with Lets Encrypt. This should be an email you have access to.
4. **Tunneling** You can choose not to install Gerbil for tunneling support - in this config it will just be a normal reverse proxy. See [how to use without tunneling](/03-Pangolin/03-without-tunneling.md).

### 3. Admin User Setup

You'll need to configure the admin user. This is the first user in the system. You will log in initially with this user.

1. **Admin Email**: Defaults to `admin@yourdomain.com` but can be customized
2. **Admin Password**: Must meet these requirements:
    - At least 8 characters
    - At least one uppercase letter
    - At least one lowercase letter
    - At least one digit
    - At least one special character

### 4. Security Settings

It will ask you to configure some basic security options. For example:

1. **Signup Without Invite**: Choose whether to disable user registration without invites (defaults to disabled). This removes the "Sign Up" button on the login form and is recommended for private deployments.
2. **Organization Creation**: Decide if users can create their own organizations (defaults to enabled)

### 5. Email Configuration

Decide whether to enable email functionality. This allows Pangolin to send transactional emails like OTP or email verification requests.

If enabled, you'll need to provide:

-   SMTP host
-   SMTP port (defaults to 587)
-   SMTP username
-   SMTP password
-   No-reply email address. This is the sender email address that Pangolin will email from. Many times this should be the same as the username.

### 6. Docker Installation

If Docker isn't already installed, the installer will:

1. Detect your Linux distribution
2. Offer to install Docker automatically
3. Install the appropriate version for your distribution

Supported distributions:

-   Ubuntu/Debian
-   Fedora
-   OpenSUSE
-   RHEL
-   Amazon Linux

### 7. Container Deployment

After configuration, the installer will:

1. Pull the necessary Docker containers
2. Create required directories
3. Generate configuration files
4. Start the containers using Docker Compose

## Post-Installation

After successful installation:

1. The system will be accessible at your configured domain
2. You can log in using the admin email and password you provided

## Notes

-   The installer checks for an existing configuration and won't overwrite it if found
-   Docker installation is optional if already present
