porter/docs/developing/setup.md

Note: if you run into any issues at all, don't hesitate to reach out on the #contributing channel in Discord!

Table of Contents

• Getting Started
  • Makefile Quickstart
  • Docker Quickstart
  • Getting PostgreSQL Access
• Project and Cluster Setup
  • Setting up a Cluster
  • Minikube on MacOS
• Setup for WSL
• Secure Localhost Setup

Getting Started

Makefile Quickstart

Prequisites: Go 1.15+ installed and Node.js/npm installed.

If working under a bash environment, the easiest way to get started is by running make start-dev. This will verify that go, npm and node are found in your path, and will start a development server on localhost:8081 with live reloading set up for both the backend and frontend. After the services are running successfully, go to project and cluster setup to complete the set up.

Docker Quickstart

After forking and cloning the repo, you should save two .env files in the repo.

First, in /dashboard/.env:

NODE_ENV=development
API_SERVER=http://localhost:8081
ENABLE_PROXY=true

Next, in /docker/.env:

SERVER_URL=http://localhost:8081
SERVER_PORT=8081
DB_HOST=postgres
DB_PORT=5432
DB_USER=porter
DB_PASS=porter
DB_NAME=porter
SQL_LITE=false

Finally, run make start-dev from the root of the project. If you have all the dependencies set up correctly, things should just work.

At this point, you can make a change to any .go file to trigger a backend rebuild, and any file in /dashboard/src to trigger a hot reload.

Getting PostgreSQL Access

The docker-compose command automatically starts a PostgreSQL instance on port 5400. You can get psql access by running the following:

psql --host localhost --port 5400 --username porter --dbname porter -W

This will prompt you for a password. Enter porter, and you should see the psql shell!

Project and Cluster Setup

After the project has spun up, you can navigate to localhost:8081 (for make quickstart) or localhost:8080 (for docker-compose quickstart) and you should be greeted with the "Log In" screen. Create a user by entering an email/password on the "Register" screen.

Setting up a Cluster

These steps will help you get set up with a minikube cluster that can be used for development. Prerequisities:

• kubectl installed locally
• Development instance of Porter is running
• Download the Porter CLI or build it using make build-cli

At the moment, we only have instructions for setting up Minikube on MacOS. However, Porter is compatible with most Kubernetes clusters, as long as the server is reachable from your host network. To connect a cluster that is currently accessible via kubectl, you can run the following steps:

1. porter config set-host http://localhost:8080 (for docker-compose quickstart) or porter config set-host http://localhost:8081 (for make quickstart).
2. porter auth login
3. porter connect kubeconfig

If you now navigate to http://localhost:8080, you should see the minikube cluster attached! There will be some limitations:

• When you launch a web application, it is not possible to expose a service that you create. Whenever you create a web service, de-select the "Expose to external traffic" option.

Minikube on MacOS

1. Install minikube, and install the hyperkit driver. The easiest way to do this is via:

   brew install minikube
   brew install hyperkit
   

2. Start minikube with the hyperkit driver:

   minikube start --driver hyperkit
   

3. Make sure that you've downloaded the latest version of the Porter CLI, and that your development version of Porter is running. Then run:

   porter config set-host http://localhost:8080
   porter auth login
   

4. Make sure that minikube is selected as the current context (kubectl config current-context), and then run:

   porter connect kubeconfig
   

Setting your email to be verified

If you are getting blocked out of the dashboard because your email is not verified (fixed in v0.6.2 of Porter, so make sure you've pulled from master recently), you can update your email in the database to `verified":

UPDATE users SET email_verified='t' WHERE id=1;

Setup for WSL

Follow the steps to install WSL on Windows here: https://docs.microsoft.com/en-us/windows/wsl/install-win10

sudo apt install xdg-utils
sudo apt install postgresql

Once WSL is installed, head to Docker Desktop and enable WSL Integration.

Secure Localhost Setup

Sometimes, it may be necessary to serve securely over https://localhost (for example, required by Slack integrations). Run the following command from the repository root:

openssl req -x509 -out ./docker/localhost.crt -keyout ./docker/localhost.key \
  -newkey rsa:2048 -nodes -sha256 \
  -subj '/CN=localhost' -extensions EXT -config <( \
   printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")

Update ./docker/.env with the following:

SERVER_URL=https://localhost

If using Chrome, paste the following into the Chrome address bar:

chrome://flags/#allow-insecure-localhost

And then Enable the Allow invalid certificates for resources loaded from localhost field.

Finally, run docker-compose -f docker-compose.dev-secure.yaml up instead of the standard docker-compose file.