wufe/polo

Git-based reverse proxy for spawning staging environments

Polo

Serve your application development branches

What is Polo

Polo is a git-based reverse proxy.

Allows you to create a web server which provides the ability to serve your web application in a specific time/branch/tag in history, using git.

You just need to specify the git commit or the branch. A new session will be created for you to navigate into.

Although it provides HTTPS support, it is not intended to be used in production.

---

Use cases

It can be used for serving your staging / QA environment.

Instead of having one application on a single host, you can let the user select which git branch to serve.

Polo will then start the application and provide a reverse proxy feature for navigation.

---

Getting started

• Download Polo from the release page

• Create one or more configuration files for your application and place them next to the application executable
  There's a minimal example configuration file called testserver.yml which contains instructions to start a little demo project.

• Start Polo from command line

More info about the installation process and the configuration file in the documentation.

---

Configuration

You must provide at least one yaml configuration file describing your application remote and how to build and run it.
The configuration file must be put next to the Polo executable file.
You can find an example of a configuration file with all the options in the folder examples.

---

State diagram

This diagram represents the states walked since the request of a session to its destruction.

---

Known issues / missing features

• Add support to command concatenations (; and &&)
• Admin interface with
  • Control over manual trigger of fetch in a git application folder
  • Application configuration CRUD UI

polo's Issues

gui using only golang

Hey @wufe

really like this project. Would work well with caddy.

anyway just wanted to suggest a pure golang gui here. It also uses pure go for git too.

https://github.com/icyphox/legit

i use it with this pure golang code that supports git binary patch
https://github.com/bluekeyes/patch2pr

Documentation needed

• Configuration of the server that hosts the documentation
• Chapters
  • Installation
  • Sample configuration
  • Configuration details
  • Using a process manager
  • Run inside docker
  • List of features
  • Session lifetime
  • API

Permalinks should really be permanent

Since permalinks are based on the checkout name (e.g. a branch, a tag or a commitID), when the checkout name disappears from the repository due to for example branch deletion, the permalink does not point to a session anymore.

Permalinks should always point to a specific commit ID.

Ideally a notification should tell the user that the branch has been merged into another branch.

Annotated tags do not get fetched

Annotated tags get not fetched from the server.

Error notifications

When a build fails, there are no notifications available.

We should consider a failed session retention policy and a graphical interface element that shows up whenever a session build fails.

Usability of logs page

The logs page is not very usable, since after the user scrolls up a bit, the page scrolls down again after 5 seconds.

We should detect a mouseleave and start the timer after that.

Branch switch inside session helper

It would be nice to add a session switcher inside the session helper user interface

Building queue

Add the possibility to enable a building queue, which would build sessions in order

Print output to stdout

Normal output should be printed out on stdout instead of stderr.

Levels panic, fatal, error and warn should still be dumped on stderr.

Pagination/Filtering/Sorting

Add pagination/filtering/sorting in available branches/tags

Permalink generation / Redirect from permalink does not work with querystring

Duplicated sessions on failed replacement

When a session gets built and tries to replaces another one, if the build process fails, the old one does not get replaced.
But if another session on the same branch succeeds, the first one does not get replaced, thus creating duplicated sessions.

Custom commands & plugins

Maybe written in JS

Duplicated sessions on restart of the application

When the application is restarted, there might be duplicated sessions.
This might happen when a started/watched session is being regenerated under the hood and the previous session is not properly deleted.

Server-client communication enhancement

Since the only system used is polling, dispatch of error notifications or similar gets hard.

We need some websockets here.

Configuration editing UI

We need some configuration editing UI

Applications menu is not visible on mobile devices

When Polo is configured with several applications, the left side menu that appears on desktop does not appear on mobile devices.

Application initialization should recover from corrupted state

When an application folder is being initialized, it may get corrupted:

• shutting down the application
• when the authentication is not correct

While on the first case the application may recover itself with automatic fetch (it needs to be checked if it is so), authentication errors get swallowed and the application folder is unrecoverable while Polo is running: it needs to be restarted.

Watched branches bypass max start retries count

It happens when a branch is watched and automatic fetch fires.
The fetch process should also check if the session is already failing to start.

Sessions aliases

A created session should have a readable alias.
The alias would be stored permanently with its commit.

The session would be identified with a struct like this

type SessionIdentifier struct {
    CommitID string
    Alias string // Previously known as checkout
    AliasType AliasType
}

const (
    AliasType string
    AliasTypeLinked AliasType = "linked" // The alias is linked to its origin checkout (e.g. a branch or a tag)
    AliasTypeMadeUp AliasType = "made-up" // The alias has been created by a random name generator
    AliasTypeUserDefined AliasType = "user-defined" // The alias has been defined by the user
)

The aliases could be used for handling secondary applications permalinks

Permalink on secondary applications

Secondary application do not currently have the ability to provide a permalink.

A UUID should be generated to accomplish this functionality.
Ideally the UUID should point to a commit and its alias.

Full fledged web terminal

Since the interaction in the terminal could be complex, we should provide an interactive pseudo-terminal on the server-side of the application, that can communicate with the client side via websocket.

The feature should be also supported on windows with its new conPTY.

If the pseudo-terminal is not supported, the command executions should of course fallback to the current execution methodologies.

Synchronization between sessions of different applications

If there are two applications with the same underlying codebase, the sessions started get synchronized between the two applications