Fizzy Documentation

The fizzy-saas gem is a companion gem used by 37signals to bundle Fizzy with their billing system and production setup.

Note: This gem depends on private git repositories and is not intended for use by third parties, though it is provided as inspiration for those running Fizzy on their own infrastructure.

Personal access tokens are long-lived tokens suitable for scripts and integrations. To use them, include the token in the Authorization header as a Bearer token.

To generate a token manually:

1. Go to your profile.
2. Navigate to the API section.
3. Click Personal access tokens.
4. Click Generate new access token.
5. Provide a description and select a permission level:
   • Read: Allows reading data from your account.
   • Read + Write: Allows reading and writing data on your behalf.

Warning: Treat access tokens like passwords. Anyone with the token can perform actions on your behalf.

curl -H "Authorization: Bearer put-your-access-token-here" -H "Accept: application/json" https://app.fizzy.do/my/identity

Prefer expanded if/else conditionals over guard clauses to improve readability, especially when nesting is involved.

Exceptions: Use guard clauses only when:

• The return is at the very beginning of the method.
• The main method body is non-trivial and spans several lines.

# Bad
def todos_for_new_group
  ids = params.require(:todolist)[:todo_ids]
  return [] unless ids
  @bucket.recordings.todos.find(ids.split(,","))
end

# Good
def todos_for_new_group
  if ids = params.require(:todolist)[:todo_ids]
    @bucket.recordings.todos.find(ids.split(","))
  else
    []
  end
end

Fizzy is deployed using Kamal. Ensure the 1Password CLI is configured to access deployment secrets.

• Production: https://app.fizzy.do/ (Uses FlashBlade bucket for blob storage).
• Beta: https://beta1.fizzy-beta.com (Uses production database and Active Storage). Deploy using: bin/kamal deploy -d beta1.
• Staging: https://app.fizzy-staging.com/ (Uses production-like but separate database and Active Storage).

General deployment command:

bin/kamal deploy

Once you have obtained the direct upload URL and headers from the direct_uploads request, upload the file binary using a PUT request to the provided URL. You must include the Content-MD5 header matching the checksum provided in the initial request.

curl -X PUT \
  -H "Content-Type: image/png" \
  -H "Content-MD5: GQ5SqLsM7ylnji0Wgd9wNA==" \
  --data-binary @screenshot.png \
  "https://storage.example.com/..."

Fizzy stores all data in /rails/storage. Because Docker containers are ephemeral, you must mount a persistent volume to this path to ensure your database and files survive restarts. You can use a named volume with the --volume flag.

docker run --volume fizzy:/rails/storage ghcr.io/basecamp/fizzy:main

Follow these ordering rules to maintain consistent code flow:

Class Method Ordering:

1. class methods
2. public methods (with initialize at the top)
3. private methods

Vertical Method Ordering: Order methods based on their invocation order. If method_a calls method_b, method_b should appear after method_a in the file.

class SomeClass
  def some_method
    method_1
    method_2
  end

  private
    def method_1
      method_1_1
      method_1_2
    end
  
    def method_1_1
      # ...
    end
    # ...
    def method_2
      method_2_1
    end
end

To install and configure the Fizzy application, run the setup script. Use the --reset flag to reset the database and re-seed it. Once configured, start the development server using bin/dev.

Access the application at http://app.fizzy.localhost:3006.

Login Instructions: Use david@example.com as the email address. To complete the sign-in, retrieve the verification code from the browser console.

bin/setup
bin/setup --reset # Reset the database and seed it

# Start the server
bin/dev

Rich text fields in Fizzy accept HTML input. The input is automatically sanitized to remove unsafe tags and attributes. When sending data for a rich text field, provide the HTML string as the value for the corresponding key.

{
  "card": {
    "title": "My card",
    "description": "<p>This is <strong>bold</strong> and this is <em>italic</em>.</p><ul><li">Item 1</li><li">Item 2</li></ul>"
  }
}