Workflow: Adding a Server

Overview

This workflow guides you through adding a new RxDB server configuration to FlowState. By the end, you'll have a fully configured server ready for data synchronization.

Time Required: ~3-5 minutes Skill Level: Beginner

Prerequisites

Before starting this workflow, ensure you have:

• Access to the FlowState application
• Server connection details:
  • Server URL (e.g., https://api.example.com:7443)
  • Database name
  • Domain ID (for multi-tenant setups)
• (Optional) Email address for authentication

Workflow Diagram

+------------------+     +------------------+     +------------------+
|   Open Servers   | --> |   Click Add     | --> |   Fill in Form   |
|      App         |     |     Server       |     |     Details      |
+------------------+     +------------------+     +------------------+
                                                          |
                                                          v
+------------------+     +------------------+     +------------------+
|   Set Active     | <-- |   Save Server    | <-- | Test Connection  |
|   (Optional)     |     |                  |     |   (Optional)     |
+------------------+     +------------------+     +------------------+
         |
         v
+------------------+
|   Authenticate   |
|   (Optional)     |
+------------------+

Steps

Step 1: Open the Add Server Dialog

From the Servers App main page, initiate adding a new server.

Options:

• Click the Add Server button in the top-right area
• Press Cmd+N (macOS) or Ctrl+N (Windows/Linux)

The server configuration dialog opens with default values pre-filled.

Step 2: Configure Server Details

Fill in the server configuration fields:

Tips:

• Use descriptive names to distinguish between servers (e.g., "Local Dev", "Staging", "Production")
• Ensure the URL includes the protocol (https://) and port if not standard
• Domain ID should match your organization's configured domain on the server

Step 3: Test the Connection (Recommended)

Before saving, verify the server is accessible.

1. Click the Test Connection button
2. Wait for the connection attempt to complete
3. Look for the result indicator:
   • Green checkmark: Connection successful
   • Red X: Connection failed (see error message)

If connection fails:

• Verify the URL is correct
• Check that the server is running
• Ensure no firewall is blocking the connection
• See Troubleshooting for detailed solutions

Step 4: Save the Server Configuration

Once the details are correct:

1. Click the Save button
2. The dialog closes
3. The new server appears in the server list
4. Status shows as "Inactive" until set as active

The server is now configured but not yet active for replication.

Step 5: Set as Active Server (Optional)

To use this server for data replication:

1. Find the server in the list
2. Click the Set Active button in the Actions column
3. Confirm if prompted
4. The server now shows:
   • A star icon next to the name
   • "Active" status badge

Only one server can be active at a time. Setting a new server as active automatically deactivates the previous one.

Step 6: Authenticate (Optional)

If you need to sync data with the server:

1. Click the Login button in the Auth column
2. You're redirected to the login page for this server
3. Enter your email address
4. Click Send Code
5. Check your email for the verification code
6. Enter the 6-digit code
7. Click Verify
8. Upon success, you're redirected back to the server list

The server now shows "Authenticated" in the Auth column.

Expected Results

After completing this workflow, you should have:

Your data will now sync with the configured server when changes are made in any FlowState application.

Quick Reference

Keyboard Shortcuts:

• Cmd/Ctrl+N - Open Add Server dialog
• Cmd/Ctrl+S - Sync now (when server selected)

Minimum Required Fields:

• Server Name
• URL
• Database Name

Troubleshooting

Issue: URL Validation Error

Solution: Ensure the URL includes:

• Protocol: https:// or http://
• Host: localhost or domain name
• Port: :7443 (if non-standard)

Issue: Connection Timeout

Solution:

1. Verify the server is running
2. Check network connectivity
3. Ensure no VPN or firewall blocking

Issue: "Server Already Exists" Error

Solution: Each server name must be unique. Use a different name or edit the existing server.

See Troubleshooting for more solutions.

Related Workflows

• Features & Capabilities - Detailed feature documentation
• Getting Started - Initial setup guide
• FAQ - Common questions about servers