Documentation

Setup guides and troubleshooting for F-Bar on macOS and iOS.

Getting Started

Welcome to F-Bar. This guide will help you connect your Laravel Forge account and perform your first action.

1. Generate API Token

F-Bar communicates with Forge securely via their API. You need to create a dedicated token.

  1. Log in to your Forge Dashboard.
  2. Navigate to Account Settings → API.
  3. Click Create Token. Name it "F-Bar". Make sure the token has access to servers and sites.

Important: Forge only shows the token once. Copy it to your clipboard immediately.

2. Connect the App

Launch F-Bar on your Mac. On the welcome screen, paste the API token you just copied. F-Bar will immediately sync your servers.

Note: If you have many servers, the initial sync might take a couple of seconds.

3. Your First Action

Let’s verify everything is working.

  1. Click the F-Bar icon in the menu bar.
  2. Navigate to a staging or test site.
  3. Select Open in Forge.

Your browser should open the correct site in the Forge dashboard.

This confirms that the API connection and permissions are working correctly.

Servers

Your active servers are listed in the main menu. Each server provides the following actions:

  • Open Terminal: Opens an SSH session to the server in your preferred terminal app.
  • Copy IP address: Copies the public IP to your clipboard.
  • Open in Forge: Direct link to the server's dashboard in Laravel Forge.
  • Reboot: Reboots the entire operating system.
  • Restart Services: Individual options to restart Nginx, MySQL, Postgres, or PHP.
    Note: Rebooting PHP restarts the default PHP version selected for that server.
  • Upload SSH-key: Uploads your computer’s default public key to Forge. 
    Useful for first-time connections. Use this, wait a few seconds for propagation, then log in via SSH.
  • Logs: Display Nginx Access and error logs

Sites

Expanding a server reveals its sites. Actions available for each site:

  • Deploy: Triggers the deployment script for the site.
  • Reboot PHP: Restarts PHP-FPM and Opcache for the specific PHP version used by this site.
  • View Deployment Log: Retrieves the output of the last deployment.
  • Site Log: Retrieves the output of the Laravel logs-files.
  • Open Terminal: SSH shortcut that opens directly to the site's root directory.
  • Deployment script: View and edit the deploy script.
  • Edit .env: Edit environment variables.
    If you leave APP_DEBUG=true, F-Bar may warn you as a safety precaution.
  • Edit Nginx Configuration: Edit the site's Nginx config.
  • Notify on Deploy: Get a push notification when deploy is done. If enabled in preferences and dont-disturb mode is off
  • Visit Site: Opens the URL in your default browser.

Preferences

General Settings

  • Open Terminal in: Select your preferred app (Terminal, iTerm2, or Hyper).
  • Action Bar Hotkey: Brings up the F-Bar action bar palette.

Permission Required: The first time you use a terminal shortcut, macOS will ask to grant F-Bar permission to control other apps. This is required for AppleScript to launch the session.

Server Visibility

Hide in Menu: You can uncheck specific servers in Preferences to hide them from the menu bar list (e.g., old or unused servers). They remain accessible via Forge.

Use Internal IP: Check this if you want the "Open Terminal" shortcut to use the server's private network IP (useful for VPNs).

Monitoring & Notifications

How Monitoring Works

F-Bar runs a lightweight, local uptime monitor using a separate process (low memory footprint).

  • Mechanism: Uses cURL to send HTTP requests to your sites at a set interval.
  • Local Check: This is not part of the Forge API. It runs locally on your machine.
  • Alerts: If a site returns a non-200 status, you receive a desktop notification.

Notifications (APN)

You can receive push notifications when deployments complete.

This works by adding a webhook in Laravel Forge. F-Bar's servers receive the hook and forward it to the Apple Push Notification service (APN), which delivers it to your Mac or iOS device.

Troubleshooting

Permissions

If "Open Terminal" does nothing, ensure F-Bar has automation permissions in System Settings → Privacy & Security → Automation.

Missing Servers

Press Cmd + R while the menu is open to force a refresh of the server list from the API.

Support

Still stuck? Contact support via the email listed on the website.

Contact & Support

Need help with something not covered here? As an indie developer, I read every email. Email me at janne@eastwest.se

Här kan du lämna ett meddelande åt oss