---
title: "Convert to Remote Node"
description: "Learn how to convert your Community or Enterprise Edition Pangolin instance to a remote node"
---

## Who is this for? 

Use this guide if you have a self-hosted Pangolin instance and want to convert it to a remote node deployment. It's pretty easy!

## What will happen to my data? 

<Warning>
**Always backup your data before updating.** Copy your `config` directory to a safe location so you can roll back if needed.
</Warning>

Your existing Pangolin data will stay in the database, so feel free to try a remote node deployment without losing anything. If you want to go back, just reverse these steps.

## Migration

<Steps>
<Step title="Sign up">
    Create an account on [Pangolin Cloud](https://pangolin.fossorial.io/auth/signup) if you don't have one already.
</Step>

<Step title="Generate credentials">
    In the Pangolin Cloud dashboard, navigate to the "Self-hosted" section and generate a new ID and secret for this node. Make sure to copy this config, as you'll need it later.
</Step>

<Step title="Prepare your instance">
  On your self-hosted Pangolin server:
  
  1. Stop the Pangolin service:
     ```bash
     docker-compose down
     ```
  2. Ensure you have a backup of your `config` directory.
  3. Make sure your instance is [up to date](/self-host/how-to-update) with the latest versions of Pangolin, Gerbil, and Traefik.
</Step>


<Step title="Paste in the credentials">
    Edit your `config/config.yml` and paste the generated ID and secret managed config at the bottom of the file:
    
    ```yaml
    managed:
        id: <your-generated-id>
        secret: <your-generated-secret>
    ```

    You can leave the rest of your config the same.
</Step>


<Step title="Update your docker-compose">
    We need to update your `docker-compose.yml` file to use the new managed configuration. Its a good idea to backup the old one.

    First change the gerbil port `443:443` to `443:8443`. This will send traffic to the Gerbil SNI proxy server before hitting Traefik downstream.

    ```
    gerbil:
        ports:
            - "443:8443" # <----- It should look like this now
    ```

    Second, add a volume to sync the certs and file based Traefik config between Pangolin and Traefik. At the bottom of the file:

    ```yaml
    volumes:
        pangolin-data:
    ```

    Then in Traefik:
    ```yaml
    traefik:
        volumes:
            - ./config/traefik:/etc/traefik:ro # Volume to store the Traefik configuration
            - ./config/letsencrypt:/letsencrypt # Volume to store the Let's Encrypt certificates
            - ./config/traefik/logs:/var/log/traefik # Volume to store Traefik logs
            # Shared volume for certificates and dynamic config in file mode
            - pangolin-data:/var/certificates:ro
            - pangolin-data:/var/dynamic:ro
    ```

    And in Pangolin
    ```yaml
    pangolin:
        volumes:
            - ./config:/app/config
            - pangolin-data:/var/certificates
            - pangolin-data:/var/dynamic
    ```
</Step>

<Step title="Change the repo and tag">
    Update the Pangolin repo to use the remote node image. In your `docker-compose.yml`, change the `pangolin` service to use the remote image:

    ```yaml
    pangolin:
        image: fosrl/pangolin-node:latest
    ```
</Step>

<Step title="Add ping to Traefik">
    Edit your `config/traefik/traefik_config.yml` file to add a ping endpoint for health checks. Add this to the bottom of the file:

    ```yaml
    ping:
        entryPoint: "web"
    ```
</Step>

<Step title="Bring up the stack">
    Start the updated stack with Docker Compose:
    ```bash
    docker-compose up -d
    ```
</Step>

<Step title="Configure your account">
    Pangolin is now controlled through the [Pangolin Cloud](https://pangolin.fossorial.io/auth/signup) dashboard. Make sure to bring your domain and recreate your sites and resources.

    <Tip>
    If you move your whole domain away from your VPS to Pangolin Cloud, make sure to update your `base_endpoint` under the `gerbil:` section of your `config.yml` to be the IP address of your instance otherwise we cant resolve your instance in DNS.
    </Tip>

    In the future, we plan to allow importing config!
</Step>

</Steps>
