Getting Started with CasaOS and Twingate

Overview

This guide explains how to set up Twingate to securely access your CasaOS environment using the open source CasaOS App Store. By integrating Twingate with CasaOS, you can ensure that your private resources remain protected while enabling seamless remote access.

Prerequisites

Before you begin, ensure you have the following:

• A running instance of CasaOS.
• A Twingate account with access to the Admin Console.

Installation Steps

1. Generate Connector Access and Refresh Tokens

Start by generating new Access and Refresh tokens for a Connector. Follow these steps:

• Log in to the Twingate Admin Console.
• Navigate to Remote Networks.

  

• Select the Remote Network you want to add a Connector to.
• Add a Connector or select one that hasn’t been deployed yet.

  

• Select See More

  

• Select the Manual option.

  

• Scroll down to Step 2 and click Generate Tokens.

  

• Authenticate when prompted to complete token generation.
• Copy the Access Token and Refresh Token displayed. These will be used in the next step.

2. Deploy the Connector using a custom App Store installation

• Open the CasaOS web UI.

  

• Navigate to the App Store.
• Click on the “Custom Install” button in the top right hand corner.

  

• Click on the “Import” button in the top right hand corner of the “Manual App Install” page.

  

• Copy and paste the following into the docker-compose section:

name: twingate-connector
services:
  twingate-connector:
    image: twingate/connector:1
    container_name: twingate-connector
    command:
      - /connectord
    environment:
      TWINGATE_NETWORK: ""
      TWINGATE_ACCESS_TOKEN: ""
      TWINGATE_REFRESH_TOKEN: ""
      TWINGATE_LABEL_DEPLOYED_BY: "casaos"
      TWINGATE_LABEL_HOSTNAME: ""

    restart: unless-stopped
    network_mode: default
    privileged: false
    cpu_shares: 90
    x-casaos:
      envs:
        - container: TWINGATE_NETWORK
          description:
            en_us: "Name of the Twingate Network to connect to. Example: 'https://{network_name}.twingate.com'"
        - container: TWINGATE_ACCESS_TOKEN
          description:
            en_us: "The Twingate Access Token. You can generate one from the Twingate Admin Console."
        - container: TWINGATE_REFRESH_TOKEN
          description:
            en_us: "The Twingate Refresh Token. You can generate one from the Twingate Admin Console."
        - container: TWINGATE_LABEL_HOSTNAME
          description:
            en_us: "The hostname label for the Twingate Connector."
    deploy:
      resources:
        reservations:
          memory: 500M  # Modify as needed

x-casaos:
  architectures:
    - amd64
    - arm64
    - arm
  main: twingate-connector
  category: Network
  description: 
    en_us: "Install the Twingate Connector on CasaOS to securely connect your home network to the Twingate network. This allows you to access your home network resources from anywhere without exposing them to the internet."
  developer: Twingate
  icon: https://cdn.jsdelivr.net/gh/IceWhaleTech/CasaOS-AppStore@main/Apps/Twingate/icon.png
  screenshot_link:
  tagline:
    en_us: Twingate Connector for CasaOS
  thumbnail: https://cdn.jsdelivr.net/gh/IceWhaleTech/CasaOS-AppStore@main/Apps/Twingate/thumbnail.png
  title:
    en_us: Twingate Connector for CasaOS

• Click the “Submit” button to save the custom app configuration.

  

• Dismiss the pop up by clicking the “Ok” button.

  

• Select “https” in the “Web UI” dropdown and add {network_name}.twingate.com/networks/overview to the next box, replacing {network_name} with the name of your Twingate Network. This will allow you to easily access the Twingate Admin Console by clicking on the Twingate Connector app on the CasaOS dashboard.

  

• Fill out the “Environment Variables” section with the appropriate values for your Twingate account and network. This includes the tokens you copied in step 1.8. Your Twingate Network name is the subdomain of your Twingate network URL. For example, if your Twingate network URL is https://example.twingate.com, then your Twingate Network name is example.
• Click the “Install” button to deploy the Twingate Connector on your CasaOS instance.

  

  

3. Verify Installation

• Navigate back to the Admin Console.
• Navigate to Remote Networks.
• Select the Remote Network you added your new Connector to.
• Select the new Connector.
• Verify that the Controller and Relay statuses are Connected.

  

4. Access Your CasaOS Dashboard Remotely

• Navigate to the Twingate Admin Console.
• Click on Resources in the top sub menu.
• Click the ”+ Resource” button in the top right corner.
• Select the Remote Network you just installed your Connector on.
• Give the resource a name (e.g., “CasaOS Dashboard”).
• Add the dashboard’s private IP address. This will be the same address used to access the dashboard locally. It is typically in the format 192.168.x.x.
• Assign access to one of your groups by selecting one in the list and clicking “Grant Access”.
• Now anyone in that selected group will have access to the CasaOS dashboard when connected to Twingate. To access the dashboard, simply connect to Twingate and navigate to the dashboard’s IP address. You should see the CasaOS dashboard load as if you were accessing it locally!

Troubleshooting

Common Issues

• Token Errors: Ensure the Access and Refresh tokens are correctly entered.
• Connectivity Problems: Verify that you can access the CasaOS web interface locally and the Twingate Connector app is running.

For more general troubleshooting information, refer to the troubleshooting docs.

Next Steps

Once Twingate is configured, you can explore additional resources to enhance your setup:

• Home Assistant Setup Guide: Learn how to integrate Twingate with Home Assistant, the easy way.
• Unraid Helper Script Guide: Learn how to integrate Twingate with Unraid with the official Community App.
• ZimaOS Setup Guide: Learn how to integrate Twingate with ZimaOS.
• Setting Up Resources: Learn how to configure Twingate Resources to gain access to private applications and services.