Tramline
Release coordination and deployment platform, just for your mobile apps
Install / Use
/learn @tramlinehq/TramlineREADME
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:
<figure> <img alt="setup architecture" src="art/overall-arch@1x.png" width="90%" /> </figure>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
bin/setup.mac
Generate production credentials and follow the instructions
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:
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.
<p> <a href="https://render.com/deploy" target="_blank"> <img src="https://render.com/images/deploy-to-render-button.svg" alt="Deploy to Render"> </a> </p>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
applelinksection from therender.yamlfile. - 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.
integrations:
applelink:
iss: "tramline.dev"
aud: "applelink"
secret: "any password"
- Commit your changes and resync the blueprint on Render. This will kick-off the
applelinkservice. This will most likely fail to deploy on the first attempt, because it requires certain environment configuration. To do that, create aSecret Fileunderapplelink > Settings > Environment > Secret Filescalled.envand update with the following details by putting the applelink secret from the previous step underAUTH_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_URLtosite-webwith the final DNS of theapplelinkservice. - The
HOSTNAMEinsite-webandsite-jobsmust be updated to point to the DNS ofsite-web(without the protocol).
Once all services on Render are green, your setup should look like this:
<figure> <img alt="render.com services" src="art/render_dotcom_services.png" width="90%" /> </figure>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,
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
