Accessing Preview Environments

Accessing Preview Environments #

This guide shows you how to find and access your Preview Environment after it’s been created.

Finding the Preview URL #

There are three ways to access your Preview Environment:

Method 1: PR Comments (Easiest) #

  1. Navigate to your Pull Request on GitHub
  2. Scroll to the comments section
  3. Look for the automated comment from “github-actions” bot:
🎉 Preview environment created!

| Resource | URL |
|----------|-----|
| 🌐 Application | [Open Preview](https://app--dev--coder-preview-123--john.coder.internal.gotofu.com/) |

Workspace: coder-preview-123
  1. Click the “Open Preview” link

Method 2: PR Description #

  1. Go to your Pull Request
  2. Look at the PR description (top of the page)
  3. You’ll see a section like this:
## 🚀 Preview Environment

Your preview environment is ready!

| Resource       | URL                                                                  |
| -------------- | -------------------------------------------------------------------- |
| 🌐 Application | https://app--dev--coder-preview-123--john.coder.internal.gotofu.com/ |

Workspace: coder-preview-123

💡 Note: This environment will be automatically updated when you push new commits,
and deleted when the PR is closed.

Method 3: Coder Dashboard #

  1. Go to Coder Workspaces
  2. Find your workspace named coder-preview-{PR-number}
  3. Click on it to open the workspace page
  4. Look for the “Apps” section
  5. Click on the “app” link

Understanding the URL Structure #

Preview Environment URLs follow this format:

https://app--dev--{workspace-name}--{owner}.coder.internal.gotofu.com/

Components:

  • app - The application subdomain (main BonsAI app)
  • dev - The Coder template being used
  • {workspace-name} - Your workspace name (e.g., coder-preview-123)
  • {owner} - The Coder username who owns the workspace
  • coder.internal.gotofu.com - Coder domain

Example:

https://app--dev--coder-preview-123--john.coder.internal.gotofu.com/

Available Services #

Each Preview Environment exposes multiple services:

Main Application #

  • URL Pattern: https://app--dev--{workspace}--{owner}.coder.internal.gotofu.com/
  • Description: The main BonsAI web application
  • Port: 9000 (proxied through Nginx)
  • Use For: Testing frontend features, user workflows

Swagger Editor #

  • URL Pattern: https://swagger-editor--dev--{workspace}--{owner}.coder.internal.gotofu.com/
  • Description: Interactive API specification editor
  • Port: 8000
  • Use For: Editing and testing OpenAPI specifications

Internal API Documentation #

  • URL Pattern: https://swagger-internal--dev--{workspace}--{owner}.coder.internal.gotofu.com/
  • Description: Internal API documentation (Swagger UI)
  • Port: 8001
  • Use For: Viewing API endpoints and testing API calls

CloudBeaver (Database Management) #

  • Access Via: Coder workspace apps section
  • Description: Web-based database management tool
  • Port: 8978
  • Use For: Inspecting database state, running queries

Portainer (Docker Management) #

  • Access Via: Coder workspace apps section
  • Description: Docker container management interface
  • Port: 9443
  • Use For: Viewing container logs, restarting services

Authentication #

First-Time Access #

When you first access the Preview Environment:

  1. You’ll be redirected to the authentication page
  2. Sign in with your BonsAI credentials
  3. You’ll be automatically redirected back to the application
  4. Your session will be maintained for subsequent visits

Session Management #

  • Session Duration: 24 hours
  • Re-authentication: Required after session expires
  • Shared Access: Each user must authenticate separately

Sharing with Team Members #

For Developers and QA #

Team members can access the Preview Environment using the same URL:

  1. Share the preview URL from the PR comments or description
  2. Recipients must authenticate with their own credentials
  3. All users see the same environment and data

Example Message:

Hi team! Please test my new feature in this preview environment:
https://app--dev--coder-preview-123--john.coder.internal.gotofu.com/

Focus areas:
- Invoice processing workflow
- Xero integration sync

Let me know if you find any issues!

For External Stakeholders (Customers, Partners) #

⚠️ Note: Preview environments are internal only. For external demos:

  1. Create a test account in the preview environment
  2. Record a demo video or screenshots
  3. Alternatively, use the staging environment for external demos

Testing Different Scenarios #

As a Regular User #

  1. Access the main application URL
  2. Sign in with your test account
  3. Navigate through the features being tested
  4. Verify functionality works as expected

As a Developer (API Testing) #

  1. Access the Internal API Documentation URL
  2. Use the Swagger UI to test API endpoints
  3. Check request/response payloads
  4. Verify authentication and authorization

As a QA Engineer #

Frontend Testing:

  1. Access the main application
  2. Test user workflows end-to-end
  3. Verify UI/UX changes
  4. Check different screen sizes and browsers

Backend Testing:

  1. Use Swagger UI for API testing
  2. Access CloudBeaver for database inspection
  3. Check background job processing
  4. Verify integration behavior

Integration Testing:

  1. Configure integrations (see Integration Setup)
  2. Test data sync workflows
  3. Verify external service connections
  4. Check error handling

Browser Considerations #

Supported Browsers #

Preview Environments work best with:

  • ✅ Chrome (recommended)
  • ✅ Firefox
  • ✅ Safari
  • ✅ Edge

Browser Settings #

SSL/TLS Certificates:

  • The preview environment uses valid SSL certificates
  • No need to accept security warnings

Cookies:

  • Ensure cookies are enabled for authentication
  • Session cookies are required

JavaScript:

  • Must be enabled
  • The application won’t work without it

Accessing Workspace Terminal #

For advanced debugging, you can access the workspace terminal:

Via Coder Web Terminal #

  1. Go to Coder Workspaces
  2. Find your workspace (coder-preview-{PR-number})
  3. Click on the workspace name
  4. Click “Terminal” in the top navigation
  5. You now have shell access to the environment

Via SSH (Advanced) #

If you prefer SSH access:

  1. Go to your Coder workspace page
  2. Click “Connect via SSH” in the workspace details
  3. Copy the SSH command
  4. Run it in your local terminal

Example:

ssh coder.coder-preview-123

Common Terminal Commands #

Once in the terminal:

# Check service status
cd ~/bonsai
docker compose -f docker-compose.preview.yml ps

# View service logs
docker compose -f docker-compose.preview.yml logs -f bonsapi

# Restart a service
docker compose -f docker-compose.preview.yml restart webapp

# Run database migrations
mise run db-migrate

# Access database shell
psql $DATABASE_URL

Mobile Testing #

While Preview Environments are optimized for desktop testing:

Option 1: Responsive Mode #

  1. Open Chrome DevTools (F12)
  2. Click the device toggle icon
  3. Select a mobile device preset
  4. Test responsive behavior

Option 2: Actual Device Testing #

  1. Ensure your mobile device is on the same network
  2. Access the preview URL on your mobile browser
  3. Sign in with your credentials
  4. Test mobile-specific features

⚠️ Note: Mobile devices must have network access to *.coder.internal.gotofu.com. This typically requires VPN access for remote devices.

Environment Information #

How to Find Environment Details #

Workspace Name:

  • Look in PR comments or description
  • Format: coder-preview-{PR-number}

Build Version:

  • Check the GitHub Actions run number
  • View commit SHA in the PR

Runtime Info:

  • Instance type: t3.2xlarge
  • Memory: 32 GB
  • CPU: 8 vCPUs
  • Storage: 500 GB

Checking Service Health #

Use the Coder workspace terminal:

# Check all services
docker compose -f docker-compose.preview.yml ps

# Check individual service health
docker inspect --format='{{.State.Health.Status}}' bonsapi

# View resource usage
docker stats

Limitations and Considerations #

Performance #

  • Preview environments run on t3.2xlarge instances
  • May be slower during builds or heavy operations

Data Isolation #

  • Each preview has its own database
  • Data is NOT shared between previews or with production
  • Data persists during updates but is deleted when PR closes

External Services #

  • Integration credentials need manual configuration
  • OAuth redirects must be updated for preview URL
  • See Integration Setup for details

Concurrent Users #

  • Multiple users can access simultaneously
  • Recommended max: 5 concurrent users
  • Performance may degrade with heavy concurrent usage

Next Steps #