tramlinehq/tramline — Gitpedia

<picture> <source media="(prefers-color-scheme: dark)" srcset="art/tramline-fff-medium.png"> <img alt="the tramline logo" src="art/tramline-logo-medium.png"> </picture> <h1 align="center">Tramline</h1> Release apps without drowning in process Codify your app's release cycle, deploy builds with increased confidence, and give visibility to the entire organization. <a href="https://tramline.app" target="_blank" rel="noopener noreferrer">Website</a> · <a href="https://tramline.substack.com" target="_blank" rel="noopener noreferrer">Latest Updates</a> · <a href="https://tramline.app/blog" target="_blank" rel="noopener noreferrer">Blog</a> <a href="https://twitter.com/tramlinehq/" target="_blank" rel="noopener noreferrer"> <img alt="Twitter Follow" src="https://img.shields.io/twitter/follow/tramlinehq?style=social"> </a> <a href="https://go.tramline.app/discord" target="_blank" rel="noopener noreferrer"> <img alt="Discord" src="https://img.shields.io/discord/974284993641725962?style=plastic"> </a> <a href="https://github.com/tramlinehq/site/actions/workflows/ci.yml"> <img src="https://github.com/tramlinehq/site/actions/workflows/ci.yml/badge.svg?branch=main" /> </a> <a href="https://github.com/testdouble/standard"> <img src="https://img.shields.io/badge/code_style-standard-brightgreen.svg" /> </a> <a href="CODE_OF_CONDUCT.md"> <img src="https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg" /> </a> <img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/m/tramlinehq/tramline">

Features ✨

Release dashboards

A centralized dashboard to monitor and control all your mobile releases, that gives visibility into the release process to all stakeholders.

Release trains

Using the release train model, you can setup different types of releases as separate trains comprising of different steps. For e.g. your production release train can look completely different from the release train that does frequent internal deploys.

Integrations

Connect with all the essential tools you use during your release cycle: version control, notifications, CI/CD (build) servers, distribution services, and both App Store and Play Store.

Automations

Save time and reduce human error across the board by automating release-specific chores. For e.g.

Create a new release branch for every release
Create and merge release-specific branches, as determined by your branching strategy
Submit build to the Store only after explicit approval
Tag the final release build commit
Don't allow starting a new release unless previous release-specific commits have landed in the working branch

Analytics

Track and visualize release-specific metadata that you need to make informed decisions: release frequency, build times, review times, etc.

How to set it up yourself ⚙️

These steps assume setting it up on Render only. However, the instructions are standard enough to be adapted for a Heroku deployment or even bare-metal. A Dockerized setup is in the works and will come shortly.

[!NOTE]
Since Render does not offer background workers under the free plan, you will have to put in your payment details to fully complete this deployment.

Requirements

At minimum, you'll need the following to get Tramline up and running:

This repository set up as the primary monolithic backend
This repository set up as a background worker
Postgres database
Redis, preferably persistent

You'll also need to set up integrations for Tramline to be useful:

Setting up integration apps

The guides above should help you setup the OAuth apps as necessary. They may ask you to fill up a redirect URL, this URL should be updated with the final DNS after everything is setup towards the end.

Google Cloud Platform

We need to setup GCP for storing builds in Tramline. After creating your service account as mentioned above, please create a GCS bucket named artifact-builds-prod to host your builds.

Setting up Tramline

The deployment architecture looks like this:

To begin, first clone this repo. This ensures everything that you do is fully under your control.

In case you'd like to run this locally first, please follow the local development instructions.

To host Tramline directly, you'll need to prep your fork:

Set up Rails

bash
bin/setup.mac

Generate production credentials and follow the instructions

bash
bin/setup.creds -e prod

Keep the production.key file safe and don't commit it!

Update production credentials

After adding the encryption credentials, fill in the following details for the integrations in production.yml.enc by running bin/rails credentials:edit --environment production.

Follow the links mentioned earlier to setup the bare-minimum integrations.

For applelink, choose any string as your secret. We will use this later.

Use the following template:

yaml
active_record_encryption:
  primary_key:
  deterministic_key:
  key_derivation_salt:

secret_key_base:

dependencies:
  postmark:
    api_token:

  gcp:
    project_id:
    private_key_id:
    private_key: |
    client_email:
    client_id:
    client_x509_cert_url:

integrations:
  slack:
    app_id:
    client_id:
    client_secret:
    signing_secret:
    verification_token:
    scopes: "app_mentions:read,channels:join,channels:manage,channels:read,chat:write,chat:write.public,files:write,groups:read,groups:write,im:read,im:write,usergroups:read,users.profile:read,users:read,users:read.email,commands,usergroups:write"

  applelink:
    iss: "tramline"
    aud: "applelink"
    secret: "any password"

  github:
    app_name:
    app_id:
    private_pem: |

Save the credentials file and commit your changes. Use this button from your fork to kick-off a Render deployment.

The blueprint will ask for the RAILS_MASTER_KEY. Use the contents of production.key from the previous step.

Setup applelink

If you would like to use the App Store integration, you'd have to configure the applelink service. You can skip this section otherwise.

To start off, in your fork, uncomment the applelink section from the render.yaml file.
Secondly, to your encryption file, add this to the integrations section, by running bin/rails credentials:edit --environment production. Choose a secret key for authorization.

yaml
integrations:
  applelink:
    iss: "tramline.dev"
    aud: "applelink"
    secret: "any password"

Commit your changes and resync the blueprint on Render. This will kick-off the applelink service. This will most likely fail to deploy on the first attempt, because it requires certain environment configuration. To do that, create a Secret File under applelink > Settings > Environment > Secret Files called .env and update with the following details by putting the applelink secret from the previous step under AUTH_SECRET:

RACK_ENV=production
WEB_CONCURRENCY=2
MAX_THREADS=1
PORT=3001
AUTH_ISSUER="tramline"
AUTH_AUD="applelink"
AUTH_SECRET=""
SENTRY_DSN=""

Wrap up

Before we wrap up, we need to fix a couple of ENV variables:

If you have setup applelink in the previous step, you must add an APPLELINK_URL to site-web with the final DNS of the applelink service.
The HOSTNAME in site-web and site-jobs must be updated to point to the DNS of site-web (without the protocol).

Once all services on Render are green, your setup should look like this:

That should be it! You can use the default DNS from site-web to launch Tramline. You can configure and tweak more settings later.

Local development 🛠️

Applelink

Applelink is a separate service that you will need to run Tramline locally. You must clone the Applelink repository into the same parent directory as Tramline. For example, your directory structure could look like this:

./tramline-local
  ↳ applelink/
  ↳ tramline/

If you clone Applelink inside the Tramline directory, things will not work.

Env vars

First copy the sample env file,

bash
cp .env.development.sample .env.development

.env.development is gitignored, so changes will remain local.

Pre-requisites

For local development, clone this repository and install the following pre-requisites:

docker

Follow the instructions here to install docker on your machine if you don't have it already. We recommend using Podman or OrbStack for managing containers locally.

ngrok

ngrok is used for public URLs and webhooks from third-party integrations like GitHub, GitLab, Bitbucket, etc.

One-time setup:

Sign up for free at ngrok.com
Get your authtoken from dashboard.ngrok.com/get-started/your-authtoken
Add to .env.development: LOCALTUNNEL_AUTHTOKEN=your_token_here
(Optional) Reserve a domain in ngrok dashboard and add: LOCALTUNNEL_DOMAIN=https://your-domain.ngrok.dev

Run just ports to see your tunnel URL.

To disable the tunnel, set LOCALTUNNEL_DISABLED=true in .env.development.

justfile

There's a Justfile that you can use to run common commands including starting the development environment, running specs, linting, etc.

Install just by following the instructions here.

secret credentials

If you're a trusted contributor, reach out to the existing developers for access to the dev master.key. Place the master.key file in the config directory or set RAILS_MASTER_KEY in .env.development.

If you're a new external contributor, run the following to setup your own credentials:

bash
just pre-setup

This will setup the rails credentials via an interactive script. Once this is done, you should be able to boot up the application.

[!NOTE]
Booting is insufficient to make Tramline entirely useful for dev. To run a proper release flow, you'd have to setup some basic integrations as well. See here.

Running

You can start your local development environment by running the following command:

docker compose up

Refer to lib/seed/constants.rb for credentials on how to login using the seed users.

Below are some common commands you can use via just:

just start – Starts the development environment
just spec – Runs the specs
just lint – Runs the linter
just rails command – Runs a Rails command in the web container
just rake command – Runs a Rake command in the web container
just bundle command – Runs a Bundler command in the web container
just devlog – Tails the development log
just bglog – Tails the background worker log
just shell – Opens a shell in any docker container

In case the above list is stale, run just --list to see the full list.

Integrations

Tramline is an integration-heavy service. It doesn't do much without some basic integration setup. Even though we connect to a lot of third-party services, for a basic development setup, only GitHub is truly necessary. So to setup an integration with GitHub, you must create an OAuth GitHub app first. And then run the following:

bash
just rails credentials:edit

Fill the following content/section in the credentials file:

bash
integrations:
  github:
    app_name:
    app_id:
    private_pem: |

[!TIP]
After saving credentials, restart the web service to take effect.

Webhooks

Webhooks need access to the application over the Internet and that requires tunneling on the localhost environment. ngrok is started automatically in the local development environment using Docker Compose. See ngrok for setup instructions.

Adding or updating gems

Use just bundle add <gem> to add a new gem.
To update a gem use just bundle update <gem>.

[!TIP]
You might need to restart the web, sidekiq and/or css containers after adding or updating a gem.

Using the just bundle add tool auto-applies
the pessimistic operator in the Gemfile.
Although Gemfile.lock is the correct source of gem versions, specifying the pessimistic operator makes for a simpler
and safer update path through bundler for future users.

Doing this for development/test groups is optional.

Git Worktrees

Tramline supports running multiple worktrees simultaneously for parallel development. Each worktree gets a unique port automatically assigned based on its directory name.

Prerequisites:

The main repository must be running (just start in the main repo)
Worktrees share the main repo's postgres, redis, and applelink containers

Setting up a worktree:

Create a worktree from the main repo:

bash
git worktree add ../tramline-feature-branch feature-branch

Run the setup script from the main repo to copy configuration files:
```
bash
bin/setup.worktree ../tramline-feature-branch
```
Start the main repo if not already running:
```
bash
just start
```

Start the worktree:

bash
cd ../tramline-feature-branch
just start

Check your assigned port:
```
bash
just ports
```

Each worktree will be accessible at https://tramline.local.gd:<assigned-port>.

Using pry

You can attach to a running container using the just attach <service-name> command.
Once attached, any pry session will be available in the container. To detach, press ctrl-d.