Posium LogoPOSIUM

Tunneling

How to test application that are private or behind VPN using tunneling

Whitelisting Public IP Address

Please whitelist the following IP address Public IP : 34.29.236.79

Tunneling

Posium Tunneling allows you to securely connect your local applications to Posium's cloud for testing. Follow these steps to get your tunnel up and running.

Prerequisites

Before you begin, ensure you have:

  1. Docker Installed: Docker Desktop (Windows/macOS) or Docker Engine (Linux) must be running on your machine. Get Started with Docker
  2. Posium API Key: Access your unique API key from your Posium account settings.
  3. Local Application Running: Your application must be active and listening on a specific port on your local machine (e.g., http://localhost:3000).

Step-by-Step Tunnel Setup

Step 1: Create Your Tunnel Configuration via Posium API

You'll send an API request to Posium to define which local services you want to expose.

  1. Prepare your JSON request body. This defines your local applications.

    • For an HTTP/HTTPS app, include name, type: "http" or "https", local_port.
    • For TCP/UDP services, include name, type: "tcp" or "udp", and local_port.
    • You can include multiple services in the proxies array.
    • Optionally set a timeout (in seconds) for the tunnel's lifespan.
    {
  "apiKey": "YOUR_POSIUM_API_KEY",
  "proxies": [
    {
      "name": "my-webapp",
      "type": "http",
      "local_port": 3000
    },
    {
      "name": "my-api",
      "type": "tcp",
      "local_port": 8080
    }
  ],
  "timeout": 3600
}

  2. Send the API request to POST https://api.posium.com/tunnel. Replace YOUR_POSIUM_API_KEY in the header and body with your actual key.

    curl -X POST [https://api.posium.com/tunnel](https://api.posium.com/tunnel) \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_POSIUM_API_KEY" \
  -d '{
        "apiKey": "YOUR_POSIUM_API_KEY",
        "proxies": [
          { "name": "my-webapp", "type": "http", "local_port": 3000 },
          { "name": "my-api", "type": "tcp", "local_port": 8080 }
        ],
        "timeout": 3600
      }'

  3. Receive Posium's API response. This JSON response will provide crucial details:

    • id: Your unique tunnel ID (e.g., a1b2c3d4).
    • subdomain: The generated subdomain for HTTP/HTTPS access (e.g., ua1b2c3d4.frp.posium.com).
    • allocatedPorts: Public ports assigned for your TCP/UDP tunnels (e.g., [8001]).
    • dockerEnv: A set of environment variables pre-configured for your Docker client.
    {
  "message": "Tunnel configuration created successfully",
  "data": {
    "id": "a1b2c3d4",
    "subdomain": "ua1b2c3d4",
    "allocatedPorts": [8001, 8002],
    "dockerEnv": {
      "FRPS_HOST": "frp.posium.com",
      "FRPS_PORT": 7000,
      "TUNNELS": "[{\"name\":\"my-webapp\",...},{\"name\":\"my-api\",...}]"
    }
  }
}

Step 2: Get Your Docker Command

Posium will generate a ready-to-use Docker command specific to your tunnel.

  1. Send an API request to GET https://api.posium.com/tunnel/{tunnelId}/docker-command.

    • Replace {tunnelId} with the id you received in Step 1.
    • Include serverHost=frp.posium.com and serverPort=7000.
    curl "[https://api.posium.com/tunnel/a1b2c3d4/docker-command?serverHost=frp.posium.com&serverPort=7000&imageTag=latest](https://api.posium.com/tunnel/a1b2c3d4/docker-command?serverHost=frp.posium.com&serverPort=7000&imageTag=latest)"

  2. Posium's response will contain the full dockerCommand string. Copy this entire string.

    {
  "message": "Docker command generated successfully",
  "data": {
    "tunnelId": "a1b2c3d4",
    "dockerCommand": "docker run -d --name posium-frpc-a1b2c3d4 -e FRPS_HOST=frp.posium.com -e FRPS_PORT=7000 -e FRPS_TOKEN=secret-frp-token-xyz -e TUNNELS='[{\"name\":\"my-webapp\",\"type\":\"http\",\"local_port\":3000,\"custom_domains\":[\"my-test-app.yourcompany.com\"]},{\"name\":\"my-api\",\"type\":\"tcp\",\"local_port\":8080,\"remote_port\":8001}]' posium/frp-client:latest",
    "dockerEnv": { /* ... same as above ... */ }
  }
}

Step 3: Run the Posium FRP Client Docker Container

This step establishes the secure tunnel from your machine to Posium.

  1. Open your terminal or command prompt.

  2. Paste and execute the dockerCommand you copied from Step 2.

    # Example: Your actual command will be longer
docker run -d --name posium-frpc-a1b2c3d4 \
  -e FRPS_HOST=host.docker.internal \
  -e FRPS_PORT=7000 \
  -e FRPS_TOKEN=secret-frp-token-xyz \
  -e TUNNELS='[{"name":"my-webapp","type":"http","local_port":3000},{"name":"my-api","type":"tcp","local_port":8080,"remote_port":8001}]' \
  posium/frp-client:latest
    • The -d flag runs the container in the background (detached mode).
    • The -e flags pass necessary environment variables (Posium's FRP server host, port, authentication token, and your tunnel configurations) to the FRP client.
    • posium/frp-client:latest is the official Docker image for the Posium tunneling client.

Step 4: Access Your Local Services via Posium

Once the posium-frpc Docker container is running, your local applications are now accessible through Posium's public endpoints.

  • For HTTP/HTTPS applications:
    • http://[your-tunnel-subdomain].frp.posium.com (using the subdomain from Step 1).
  • For TCP/UDP services:
    • frp.posium.com:[allocated_port] (using the allocatedPorts from Step 1).

You can now configure your Posium test runs to target these public URLs, allowing Posium's agents to interact with your local applications.

Managing Your Tunnels

You can manage your active tunnels using Posium's API endpoints:

  • Get Tunnel Details: GET https://api.posium.com/tunnel/{tunnelId}
    • Example: curl "https://api.posium.com/tunnel/a1b2c3d4"
  • List All Tunnels: GET https://api.posium.com/tunnel
    • Example: curl "https://api.posium.com/tunnel" -H "X-API-Key: YOUR_POSIUM_API_KEY"
  • Delete a Tunnel: DELETE https://api.posium.com/tunnel/{tunnelId}
    • Example: curl -X DELETE "https://api.posium.com/tunnel/a1b2c3d4" -H "X-API-Key: YOUR_POSIUM_API_KEY"
    • Note: Tunnels automatically expire after their timeout duration, so manual deletion is often only needed for early termination.

Troubleshooting

  • Check Docker Container Logs: The first step is always to check the logs of your running Posium FRP client container for error messages: 
    docker logs posium-frpc-a1b2c3d4
  • "Connection Refused" (FRP client logs):
    • Verify FRPS_HOST and FRPS_PORT are correct in your Docker command.
    • Ensure your local network/firewall allows outbound connections on the FRP server port (default 7000) to frp.posium.com.
    • Review the Docker networking tips in Step 3.
  • Application Not Responding (after tunnel is active):
    • Confirm your local application is running and accessible on the local_port you specified.
    • Check for any local firewall rules on your machine that might block the Docker container from accessing your application's port.
    • Ensure your application is configured to listen on 0.0.0.0 or 127.0.0.1 (localhost) rather than a specific network interface that Docker might not see.
  • Antivirus/Security Software: Occasionally, security software on your machine might interfere with the FRP client. You may need to whitelist posium/frp-client or Docker's network traffic.

Previous

Flake Resistance

Next

Permissions

On this page