View Source Orbit (Orbit v0.3.1)

A simple framework for a simple protocol.

Orbit is a framework for building Gemini applications, known as "capsules".

This framework focuses primarily on the Gemini protocol itself, intent on getting a request into your application, handling it, and sending a Gemtext response.

It doesn't make any assumptions about your business logic, backing database, migrations, or anything like that. If you need a database, you can add it manually (see below).

Concepts

Orbit borrows a lot of ideas from Plug and Phoenix.

• Orbit.Endpoint - the TLS server that accepts incoming requests (Phoenix.Endpoint + cowboy)
• Orbit.Request - encapsulates the request-response lifecyle (Plug.Conn)
• Orbit.Pipe - the behaviour for request middleware (Plug)
• Orbit.Router - defines pipelines and routes (Phoenix.Router)
• Orbit.Controller - processes requests (Phoenix.Controller)
• Orbit.Gemtext - renders Gemtext templates (Phoenix.Component)

Some additional niceties:

• Orbit.Static - serves up files from priv/statc (Plug.Static)
• Orbit.Status - a canonical list of all status codes
• Orbit.ClientCertificate - extracts client certificates from the request

Conventions

A basic Orbit application is structured as follows.

• MyApp - the main application business logic
• MyAppCapsule - the namespace for the Gemini app
• MyAppCapsule.Endpoint - the combined TLS server and router
• MyAppCapsule.LayoutGmi - layout templates
• MyAppCapsule.PageController - a basic controller
• MyAppCapsule.PageGmi - templates for that controller

Quickstart

Orbit does not have a fancy project generator like mix phx.new. Instead, you add the dependency to a new (or existing!) application, and then run mix orbit.init to get started.

Create a new application:

$ mix new my_app --sup

Add the dependency:

# mix.exs
def deps do
  [
    {:orbit, "~> 0.3.1"}
  ]
end

Generate some files (don't worry, existing files won't be modified):

$ mix deps.get
$ mix orbit.init my_app MyAppCapsule

Follow the instructions from the task's output.

Finally, start the application and visit gemini://localhost/

Adding a Database

This example for setting up Postgres was cribbed from the Ecto docs. You might prefer SQLite as an alternative.

Add the dependencies:

# mix.exs
def deps do
  [
    # Check hex.pm for the latest versions!
    {:ecto, "~> 3.11.2"},
    {:ecto_sql, "~> 3.11.1"},
    {:postgrex, "~> 0.17.5"}
  ]
end

Add some config:

# config/config.exs
config :my_app, ecto_repos: [MyApp.Repo]

# config/runtime.exs
config :my_app, MyApp.Repo, url: System.fetch_env!("DATABASE_URL")

Create the repo module:

# lib/my_app/repo.ex
defmodule MyApp.Repo do
  use Ecto.Repo,
    otp_app: :my_app,
    adapter: Ecto.Adapters.Postgres
end

Add the repo to the supervision tree:

# lib/application.ex
children = [
  MyApp.Repo
]

Finally, create the DB.

$ mix ecto.create

Migrations can be generated with mix ecto.gen.migration, and schemas are written by hand.