PocketBase is a realtime backend in 1 file consisting of embedded database (SQLite) with realtime subscriptions, built-in auth management and much more

<p align="center">
    <a href="https://pocketbase.io" target="_blank" rel="noopener">
        <img src="https://i.imgur.com/5qimnm5.png" alt="PocketBase - open source backend in 1 file" />
    </a>
</p>

<p align="center">
    <a href="https://github.com/pocketbase/pocketbase/actions/workflows/release.yaml" target="_blank" rel="noopener"><img src="https://github.com/pocketbase/pocketbase/actions/workflows/release.yaml/badge.svg" alt="build" /></a>
    <a href="https://github.com/pocketbase/pocketbase/releases" target="_blank" rel="noopener"><img src="https://img.shields.io/github/release/pocketbase/pocketbase.svg" alt="Latest releases" /></a>
    <a href="https://pkg.go.dev/github.com/pocketbase/pocketbase" target="_blank" rel="noopener"><img src="https://godoc.org/github.com/pocketbase/pocketbase?status.svg" alt="Go package documentation" /></a>
</p>

[PocketBase](https://pocketbase.io) is an open source Go backend that includes:

- embedded database (_SQLite_) with **realtime subscriptions**
- built-in **files and users management**
- convenient **Admin dashboard UI**
- and simple **REST-ish API**

**For documentation and examples, please visit https://pocketbase.io/docs.**

> [!WARNING]
> Please keep in mind that PocketBase is still under active development
> and therefore full backward compatibility is not guaranteed before reaching v1.0.0.

## API SDK clients

The easiest way to interact with the PocketBase Web APIs is to use one of the official SDK clients:

- **JavaScript - [pocketbase/js-sdk](https://github.com/pocketbase/js-sdk)** (_Browser, Node.js, React Native_)
- **Dart - [pocketbase/dart-sdk](https://github.com/pocketbase/dart-sdk)** (_Web, Mobile, Desktop, CLI_)

You could also check the recommendations in https://pocketbase.io/docs/how-to-use/.


## Overview

### Use as standalone app

You could download the prebuilt executable for your platform from the [Releases page](https://github.com/pocketbase/pocketbase/releases).
Once downloaded, extract the archive and run `./pocketbase serve` in the extracted directory.

The prebuilt executables are based on the [`examples/base/main.go` file](https://github.com/pocketbase/pocketbase/blob/master/examples/base/main.go) and comes with the JS VM plugin enabled by default which allows to extend PocketBase with JavaScript (_for more details please refer to [Extend with JavaScript](https://pocketbase.io/docs/js-overview/)_).

### Use as a Go framework/toolkit

PocketBase is distributed as a regular Go library package which allows you to build
your own custom app specific business logic and still have a single portable executable at the end.

Here is a minimal example:

0. [Install Go 1.25+](https://go.dev/doc/install) (_if you haven't already_)

1. Create a new project directory with the following `main.go` file inside it:
    ```go
    package main

    import (
        "log"

        "github.com/pocketbase/pocketbase"
        "github.com/pocketbase/pocketbase/core"
    )

    func main() {
        app := pocketbase.New()

        app.OnServe().BindFunc(func(se *core.ServeEvent) error {
            // registers new "GET /hello" route
            se.Router.GET("/hello", func(re *core.RequestEvent) error {
                return re.String(200, "Hello world!")
            })

            return se.Next()
        })

        if err := app.Start(); err != nil {
            log.Fatal(err)
        }
    }
    ```

2. To init the dependencies, run `go mod init myapp && go mod tidy`.

3. To start the application, run `go run main.go serve`.

4. To build a statically linked executable, you can run `CGO_ENABLED=0 go build` and then start the created executable with `./myapp serve`.

_For more details please refer to [Extend with Go](https://pocketbase.io/docs/go-overview/)._

### Building and running the repo main.go example

To build the minimal standalone executable, like the prebuilt ones in the releases page, you can simply run `go build` inside the `examples/base` directory:

0. [Install Go 1.25+](https://go.dev/doc/install) (_if you haven't already_)
1. Clone/download the repo
2. Navigate to `examples/base`
3. Run `GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build`
   (_https://go.dev/doc/install/source#environment_)
4. Start the created executable by running `./base serve`.

Note that the supported build targets by the pure Go SQLite driver at the moment are:

```
darwin  amd64
darwin  arm64
freebsd amd64
freebsd arm64
linux   386
linux   amd64
linux   arm
linux   arm64
linux   loong64
linux   ppc64le
linux   riscv64
linux   s390x
windows 386
windows amd64
windows arm64
```

### Testing

PocketBase comes with mixed bag of unit and integration tests.
To run them, use the standard `go test` command:

```sh
go test ./...
```

Check also the [Testing guide](http://pocketbase.io/docs/testing) to learn how to write your own custom application tests.

## Security

If you discover a security vulnerability within PocketBase, please send an e-mail to **support at pocketbase.io**.

All reports will be promptly addressed and you'll be credited in the fix release notes.

## Contributing

PocketBase is free and open source project licensed under the [MIT License](LICENSE.md).
You are free to do whatever you want with it, even offering it as a paid service.

You could help continuing its development by:

- [Contribute to the source code](CONTRIBUTING.md)
- [Suggest new features and report issues](https://github.com/pocketbase/pocketbase/issues)

PRs for new OAuth2 providers, bug fixes, code optimizations and documentation improvements are more than welcome.

But please refrain creating PRs for _new features_ without previously discussing the implementation details.
PocketBase has a [roadmap](https://github.com/orgs/pocketbase/projects/2) and I try to work on issues in specific order and such PRs often come in out of nowhere and skew all initial planning with tedious back-and-forth communication.

Don't get upset if I close your PR, even if it is well executed and tested. This doesn't mean that it will never be merged.
Later we can always refer to it and/or take pieces of your implementation when the time comes to work on the issue (don't worry you'll be credited in the release notes).


pocketbase

A proxy server that converts JSON request bodies to Protocol Buffers

# Welcome to Protoxy 👋
[![codecov](https://codecov.io/gh/camgraff/protoxy/branch/master/graph/badge.svg)](https://codecov.io/gh/camgraff/protoxy)
[![Go Report Card](https://goreportcard.com/badge/github.com/camgraff/protoxy)](https://goreportcard.com/report/github.com/camgraff/protoxy)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#)

## What is Protoxy?
Protoxy allows you to test your REST APIs that use [Protocol Buffer](https://developers.google.com/protocol-buffers) serialization through Postman and other API testing tools which do not natively support Protobuf encoding. Protoxy is a proxy server that converts the JSON in your request body to the appropriate Protobuf message type and transforms the response from your back-end back into JSON. You don't need to make any changes to your source code to use Protoxy.

## Install

```
go get github.com/camgraff/protoxy
```

## Usage
Consider a proto file located at `./protos/example.proto` that looks like this:

```
syntax = "proto3";
package example;

message ExampleRequest {
    string text = 1;
    int32 number = 2;
    repeated string list = 3;
}

message ExampleResponse {
    string text = 1;
}

```

1. Start the server by specifying your import paths, proto file names, and optional port.

    ```
    protoxy -I ./protos/ --port 7777 example.proto
    ```

2. Configure Postman to send requests through the Proxy server.
    ![Postman proxy config](https://raw.githubusercontent.com/camgraff/protoxy/master/media/postman-config.png)

3. Add your fully-qualified message names as params in the Content-Type header.

    ```
    Content-Type: application/x-protobuf; reqMsg="example.ExampleRequest"; respMsg="example.ExampleResponse";
    ```

4. Send your request as a raw JSON body.

    ```
    {
      "text": "some text",
      "number": 123,
      "list": ["this", "is", "a", "list"]
    }
    ```

    The response is:

    ```
    {
      "text": "this response was automagically converted to JSON"
    }
    ```

### Using Protobuf in Query String

Protoxy also supports sending protobuf messages as a base64 encoded query string in the URL. To do this, add an additional param `qs` in the header whose value corresponds to the query string parameter. For example:

```
Content-Type: application/x-protobuf; reqMsg="example.ExampleRequest"; respMsg="example.ExampleResponse"; qs="proto_body";
```

This will result in a URL like:

```
http://example.com?proto_body={base64 encoding of example.ExampleRequest}
```

### Handling Multiple Response Message Types
If your API sends multiple response message types, the `respMsg` parameter accepts a comma-seperated list of values.

```
Content-Type: application/x-protobuf; reqMsg="example.ExampleRequest"; respMsg="example.ExampleResponse,example.DifferentResponse";
```

Note: Protoxy will attempt to unmarshal your proto messages into each type of response and will send the first successful one. This can produce unexpected results because the same wire-format message can successfully be unmarshalled into multiple proto message types depending on the fields in the proto message. If possible, it is best to ensure that you back-end server returns only one response type per route.


## Author

👤 **Cam Graff**

* Github: [@camgraff](https://github.com/camgraff)
* LinkedIn: [@camgraff](https://linkedin.com/in/camgraff)

## 🤝 Contributing

Contributions, issues and feature requests are welcome!

Feel free to check [issues page](https://github.com/camgraff/protoxy/issues). 

## Show your support

Give a ⭐️ if this project helped you!


***


protoxy

Fully featured and highly configurable SFTP server with optional FTP/S and WebDAV support. It can serve local filesystem and Cloud Storage backends such as S3 and Google Cloud Storage

# SFTPGo

[![CI Status](https://github.com/drakkan/sftpgo/workflows/CI/badge.svg)](https://github.com/drakkan/sftpgo/workflows/CI/badge.svg)
[![License: AGPL-3.0-only](https://img.shields.io/badge/License-AGPLv3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

Full-featured and highly configurable event-driven file transfer solution. Server protocols: SFTP, HTTP/S, FTP/S, WebDAV. Storage backends: local filesystem, encrypted local filesystem, S3 (compatible) Object Storage, Google Cloud Storage, Azure Blob Storage, other SFTP servers.

With SFTPGo you can leverage local and cloud storage backends for exchanging and storing files internally or with business partners using the same tools and processes you are already familiar with.

## Project Status & Editions

SFTPGo is an open-source project with a sustainable business model. We offer two editions to suit different requirements, ensuring the project remains healthy and maintained for everyone.

### Open Source (Community)

Free, Copyleft (AGPLv3), Community Supported. The Community edition is a fully functional, production-ready solution widely adopted worldwide. It includes all the core protocols, storage backends, and the WebAdmin/WebClient UIs. It is ideal for:

- Standard file transfer needs.
- Integrating storage backends (S3, GCS, Azure Blob) with legacy protocols.
- Projects that are comfortable with AGPLv3 licensing.

### SFTPGo Enterprise

Commercial License, Professional Support, ISO 27001 Vendor. The Enterprise edition is built on the same core but extends it for mission-critical environments, compliance-heavy industries, and advanced workflows. It is a drop-in replacement (seamless upgrade).

| Feature | Open Source (Community) | Enterprise Edition |
| :--- | :--- | :--- |
| **License Type** | AGPLv3 (Copyleft) | **Commercial License**<br/>Proprietary/No Copyleft |
| **Vendor Compliance** | Not Applicable<br/>Community Project | **Certified Vendor**<br/>ISO 27001 & Supply Chain Validation |
| **Support** | Community (GitHub) | **Direct from Authors** |
| **Cloud Storage Engine** | Standard | **High Performance & Scalable**<br/>In-memory streaming (no local temp files) and up to 70% faster |
| **High Availability (HA)** | Standard<br/>Shared DB & Storage | **Advanced**<br/>Enhanced event handling and optimized instance coordination |
| **Automation Logic** | Simple Placeholders | **Dynamic Logic & Virtual Folders**<br/>Conditions, loops, route data across storage backends |
| **Data Lifecycle** | Delete / Retain | **Smart Archiving**<br/>Move data to external Cloud/SFTP storage via Virtual Folders |
| **Email Data Ingestion** | - | **Native IMAP Integration**<br/>Auto-extract attachments from email to storage |
| **Public Sharing** | Standard Links | **Advanced & Collaborative**<br/>Email Authentication & Group Delegation |
| **Data Protection** | - | **Encryption & Scanning**<br/>Automated PGP, Antivirus & DLP via ICAP |
| **Advanced Identity (SSO)** | Standard | **Extended Controls**<br/>Advanced Single Sign-On parameters |
| **Document Editing** | - | **Included**<br/>View, edit, and co-author in browser |

**Note**: We are committed to keeping the Open Source edition powerful and maintained. The Enterprise edition helps fund the development of the entire SFTPGo ecosystem.

## Sponsors

If you rely on SFTPGo in your projects, consider becoming a [sponsor](https://github.com/sponsors/drakkan).

Your sponsorship helps cover maintenance, security updates and ongoing development of the open-source edition.

### Thank you to our sponsors

#### Platinum sponsors

[<img src="./img/Aledade_logo.png" alt="Aledade logo" width="202" height="70">](https://www.aledade.com/)
</br></br>
[<img src="./img/jumptrading.png" alt="Jump Trading logo" width="362" height="63">](https://www.jumptrading.com/)
</br></br>
[<img src="./img/wpengine.png" alt="WP Engine logo" width="331" height="63">](https://wpengine.com/)

#### Silver sponsors

[<img src="./img/IDCS.png" alt="IDCS logo" width="212" height="51">](https://idcs.ip-paris.fr/)

#### Bronze sponsors

[<img src="./img/7digital.png" alt="7digital logo" width="178" height="56">](https://www.7digital.com/)
</br></br>
[<img src="./img/servinga.png" alt="servinga logo" width="258" height="56">](https://servinga.com/)
</br></br>
[<img src="./img/reui.png" alt="ReUI logo" width="151" height="56">](https://www.reui.io/)

## Documentation

You can explore all supported features and configuration options at [docs.sftpgo.com](https://docs.sftpgo.com/latest/).

**Note:** The link above refers to the **Community Edition**.
For details on **Enterprise Edition**, please refer to the [Enterprise Documentation](https://docs.sftpgo.com/enterprise/).

## Support

- **Community Support**: use [GitHub Discussions](https://github.com/drakkan/sftpgo/discussions) to ask questions, share feedback, and engage with other users.
- **Commercial Support**: If you require guaranteed SLAs, expert guidance, or the advanced features listed above, check out [SFTPGo Enterprise](https://sftpgo.com).

SFTPGo Enterprise is available as:

- On-premises: Full control on your infrastructure. More details: [sftpgo.com/on-premises](https://sftpgo.com/on-premises)
- Fully managed SaaS: We handle the infrastructure. More details: [sftpgo.com/saas](https://sftpgo.com/saas)

## Internationalization

The translations are available via [Crowdin](https://crowdin.com/project/sftpgo), who have granted us an open source license.

Before translating please take a look at our contribution [guidelines](https://docs.sftpgo.com/latest/web-interfaces/#internationalization).

## Release Cadence

SFTPGo follows a feature-driven release cycle.

- Enterprise Edition: Receives major new features first and follows a faster [release cadence](https://docs.sftpgo.com/enterprise/changelog/).
- Community Edition: Remains maintained, receiving bug fixes, security updates, and updates to core features.

## Acknowledgements

SFTPGo makes use of the third party libraries listed inside [go.mod](./go.mod).

We are very grateful to all the people who contributed with ideas and/or pull requests.

Thank you to [ysura](https://www.ysura.com/) for granting us stable access to a test AWS S3 account.

Thank you to [KeenThemes](https://keenthemes.com/) for granting us a custom license to use their amazing [themes](https://keenthemes.com/bootstrap-templates) for the SFTPGo WebAdmin and WebClient user interfaces, across both the Open Source and Open Core versions.

Thank you to [Crowdin](https://crowdin.com/) for granting us an Open Source License.

Thank you to [Incode](https://www.incode.it/) for helping us to improve the UI/UX.

## License

SFTPGo source code is licensed under the GNU AGPL-3.0-only with [additional terms](./NOTICE).

The [theme](https://keenthemes.com/bootstrap-templates) used in WebAdmin and WebClient user interfaces is proprietary, this means:

- KeenThemes HTML/CSS/JS components are allowed for use only within the SFTPGo product and restricted to be used in a resealable HTML template that can compete with KeenThemes products anyhow.
- The SFTPGo WebAdmin and WebClient user interfaces (HTML, CSS and JS components) based on this theme are allowed for use only within the SFTPGo product and therefore cannot be used in derivative works/products without an explicit grant from the [SFTPGo Team](mailto:support@sftpgo.com).

More information about [compliance](https://sftpgo.com/compliance.html).

**Note:** We do not provide legal advice. If you have questions about license compliance or whether your use case is permitted under the license terms, please consult your legal team.

## Copyright

Copyright (C) 2019 - 2026 Nicola Murino


SFTPGo

Simple and lightweight provider which exhibits JWTs, supports login, password-reset (via mail) and user management.

simple-jwt-provider

HTTP/2 web server with built-in support for Lua, Markdown, GCSS and Amber

algernon

Caddy is an alternative, HTTP/2 web server that's easy to configure and use

<p align="center">
	<a href="https://caddyserver.com">
		<picture>
			<source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/1128849/210187358-e2c39003-9a5e-4dd5-a783-6deb6483ee72.svg">
			<source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/1128849/210187356-dfb7f1c5-ac2e-43aa-bb23-fc014280ae1f.svg">
			<img src="https://user-images.githubusercontent.com/1128849/210187356-dfb7f1c5-ac2e-43aa-bb23-fc014280ae1f.svg" alt="Caddy" width="550">
		</picture>
	</a>
	<br>
	<h3 align="center">a <a href="https://zerossl.com"><img src="https://user-images.githubusercontent.com/55066419/208327323-2770dc16-ec09-43a0-9035-c5b872c2ad7f.svg" height="28" style="vertical-align: -7.7px" valign="middle"></a> project</h3>
</p>
<hr>
<h3 align="center">Every site on HTTPS</h3>
<p align="center">Caddy is an extensible server platform that uses TLS by default.</p>
<p align="center">
	<a href="https://github.com/caddyserver/caddy/releases">Releases</a> ·
	<a href="https://caddyserver.com/docs/">Documentation</a> ·
	<a href="https://caddy.community">Get Help</a>
</p>
<p align="center">
	<a href="https://github.com/caddyserver/caddy/actions/workflows/ci.yml"><img src="https://github.com/caddyserver/caddy/actions/workflows/ci.yml/badge.svg"></a>
	&nbsp;
	<a href="https://www.bestpractices.dev/projects/7141"><img src="https://www.bestpractices.dev/projects/7141/badge"></a>
	&nbsp;
	<a href="https://pkg.go.dev/github.com/caddyserver/caddy/v2"><img src="https://img.shields.io/badge/godoc-reference-%23007d9c.svg"></a>
	&nbsp;
	<a href="https://x.com/caddyserver" title="@caddyserver on Twitter"><img src="https://img.shields.io/twitter/follow/caddyserver" alt="@caddyserver on Twitter"></a>
	&nbsp;
	<a href="https://caddy.community" title="Caddy Forum"><img src="https://img.shields.io/badge/community-forum-ff69b4.svg" alt="Caddy Forum"></a>
	<br>
	<a href="https://sourcegraph.com/github.com/caddyserver/caddy?badge" title="Caddy on Sourcegraph"><img src="https://sourcegraph.com/github.com/caddyserver/caddy/-/badge.svg" alt="Caddy on Sourcegraph"></a>
	&nbsp;
	<a href="https://cloudsmith.io/~caddy/repos/"><img src="https://img.shields.io/badge/OSS%20hosting%20by-cloudsmith-blue?logo=cloudsmith" alt="Cloudsmith"></a>
</p>
<p align="center">
	<b>Powered by</b>
	<br>
	<a href="https://github.com/caddyserver/certmagic">
		<picture>
			<source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/55066419/206946718-740b6371-3df3-4d72-a822-47e4c48af999.png">
			<source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/1128849/49704830-49d37200-fbd5-11e8-8385-767e0cd033c3.png">
			<img src="https://user-images.githubusercontent.com/1128849/49704830-49d37200-fbd5-11e8-8385-767e0cd033c3.png" alt="CertMagic" width="250">
		</picture>
	</a>
</p>


<div align="center" markdown="1">
	<hr>
	<sup>Special thanks to:</sup>
	<br>
	<a href="https://go.warp.dev/caddy">
		<img alt="Warp sponsorship" width="400" src="https://github.com/user-attachments/assets/c8efffde-18c7-4af4-83ed-b1aba2dda394">
	</a>

### [Warp, built for coding with multiple AI agents](https://go.warp.dev/caddy)
[Available for MacOS, Linux, & Windows](https://go.warp.dev/caddy)<br>
</div>

<hr>

### Menu

- [Features](#features)
- [Install](#install)
- [Build from source](#build-from-source)
	- [For development](#for-development)
	- [With version information and/or plugins](#with-version-information-andor-plugins)
- [Quick start](#quick-start)
- [Overview](#overview)
- [Full documentation](#full-documentation)
- [Getting help](#getting-help)
- [About](#about)


## [Features](https://caddyserver.com/features)

- **Easy configuration** with the [Caddyfile](https://caddyserver.com/docs/caddyfile)
- **Powerful configuration** with its [native JSON config](https://caddyserver.com/docs/json/)
- **Dynamic configuration** with the [JSON API](https://caddyserver.com/docs/api)
- [**Config adapters**](https://caddyserver.com/docs/config-adapters) if you don't like JSON
- **Automatic HTTPS** by default
	- [ZeroSSL](https://zerossl.com) and [Let's Encrypt](https://letsencrypt.org) for public names
	- Fully-managed local CA for internal names & IPs
	- Can coordinate with other Caddy instances in a cluster
	- Multi-issuer fallback
	- Encrypted ClientHello (ECH) support
- **Stays up when other servers go down** due to TLS/OCSP/certificate-related issues
- **Production-ready** after serving trillions of requests and managing millions of TLS certificates
- **Scales to hundreds of thousands of sites** as proven in production
- **HTTP/1.1, HTTP/2, and HTTP/3** all supported by default
- **Highly extensible** [modular architecture](https://caddyserver.com/docs/architecture) lets Caddy do anything without bloat
- **Runs anywhere** with **no external dependencies** (not even libc)
- Written in Go, a language with higher **memory safety guarantees** than other servers
- Actually **fun to use**
- So much more to [discover](https://caddyserver.com/features)

## Install

The simplest, cross-platform way to get started is to download Caddy from [GitHub Releases](https://github.com/caddyserver/caddy/releases) and place the executable file in your PATH.

See [our online documentation](https://caddyserver.com/docs/install) for other install instructions.

## Build from source

Requirements:

- [Go 1.25.0 or newer](https://golang.org/dl/)

### For development

_**Note:** These steps [will not embed proper version information](https://github.com/golang/go/issues/29228). For that, please follow the instructions in the next section._

```bash
$ git clone "https://github.com/caddyserver/caddy.git"
$ cd caddy/cmd/caddy/
$ go build
```

When you run Caddy, it may try to bind to low ports unless otherwise specified in your config. If your OS requires elevated privileges for this, you will need to give your new binary permission to do so. On Linux, this can be done easily with: `sudo setcap cap_net_bind_service=+ep ./caddy`

If you prefer to use `go run` which only creates temporary binaries, you can still do this with the included `setcap.sh` like so:

```bash
$ go run -exec ./setcap.sh main.go
```

If you don't want to type your password for `setcap`, use `sudo visudo` to edit your sudoers file and allow your user account to run that command without a password, for example:

```
username ALL=(ALL:ALL) NOPASSWD: /usr/sbin/setcap
```

replacing `username` with your actual username. Please be careful and only do this if you know what you are doing! We are only qualified to document how to use Caddy, not Go tooling or your computer, and we are providing these instructions for convenience only; please learn how to use your own computer at your own risk and make any needful adjustments.

Then you can run the tests in all modules or a specific one:

```bash
$ go test ./...
$ go test ./modules/caddyhttp/tracing/
```

### With version information and/or plugins

Using [our builder tool, `xcaddy`](https://github.com/caddyserver/xcaddy)...

```bash
$ xcaddy build
```

...the following steps are automated:

1. Create a new folder: `mkdir caddy`
2. Change into it: `cd caddy`
3. Copy [Caddy's main.go](https://github.com/caddyserver/caddy/blob/master/cmd/caddy/main.go) into the empty folder. Add imports for any custom plugins you want to add.
4. Initialize a Go module: `go mod init caddy`
5. (Optional) Pin Caddy version: `go get github.com/caddyserver/caddy/v2@version` replacing `version` with a git tag, commit, or branch name.
6. (Optional) Add plugins by adding their import: `_ "import/path/here"`
7. Compile: `go build -tags=nobadger,nomysql,nopgx`




## Quick start

The [Caddy website](https://caddyserver.com/docs/) has documentation that includes tutorials, quick-start guides, reference, and more.

**We recommend that all users -- regardless of experience level -- do our [Getting Started](https://caddyserver.com/docs/getting-started) guide to become familiar with using Caddy.**

If you've only got a minute, [the website has several quick-start tutorials](https://caddyserver.com/docs/quick-starts) to choose from! However, after finishing a quick-start tutorial, please read more documentation to understand how the software works. 🙂




## Overview

Caddy is most often used as an HTTPS server, but it is suitable for any long-running Go program. First and foremost, it is a platform to run Go applications. Caddy "apps" are just Go programs that are implemented as Caddy modules. Two apps -- `tls` and `http` -- ship standard with Caddy.

Caddy apps instantly benefit from [automated documentation](https://caddyserver.com/docs/json/), graceful on-line [config changes via API](https://caddyserver.com/docs/api), and unification with other Caddy apps.

Although [JSON](https://caddyserver.com/docs/json/) is Caddy's native config language, Caddy can accept input from [config adapters](https://caddyserver.com/docs/config-adapters) which can essentially convert any config format of your choice into JSON: Caddyfile, JSON 5, YAML, TOML, NGINX config, and more.

The primary way to configure Caddy is through [its API](https://caddyserver.com/docs/api), but if you prefer config files, the [command-line interface](https://caddyserver.com/docs/command-line) supports those too.

Caddy exposes an unprecedented level of control compared to any web server in existence. In Caddy, you are usually setting the actual values of the initialized types in memory that power everything from your HTTP handlers and TLS handshakes to your storage medium. Caddy is also ridiculously extensible, with a powerful plugin system that makes vast improvements over other web servers.

To wield the power of this design, you need to know how the config document is structured. Please see [our documentation site](https://caddyserver.com/docs/) for details about [Caddy's config structure](https://caddyserver.com/docs/json/).

Nearly all of Caddy's configuration is contained in a single config document, rather than being scattered across CLI flags and env variables and a configuration file as with other web servers. This makes managing your server config more straightforward and reduces hidden variables/factors.


## Full documentation

Our website has complete documentation:

**https://caddyserver.com/docs/**

The docs are also open source. You can contribute to them here: https://github.com/caddyserver/website



## Getting help

- We advise companies using Caddy to secure a support contract through [Ardan Labs](https://www.ardanlabs.com) before help is needed.

- A [sponsorship](https://github.com/sponsors/mholt) goes a long way! We can offer private help to sponsors. If Caddy is benefitting your company, please consider a sponsorship. This not only helps fund full-time work to ensure the longevity of the project, it provides your company the resources, support, and discounts you need; along with being a great look for your company to your customers and potential customers!

- Individuals can exchange help for free on our community forum at https://caddy.community. Remember that people give help out of their spare time and good will. The best way to get help is to give it first!

Please use our [issue tracker](https://github.com/caddyserver/caddy/issues) only for bug reports and feature requests, i.e. actionable development items (support questions will usually be referred to the forums).



## About

Matthew Holt began developing Caddy in 2014 while studying computer science at Brigham Young University. (The name "Caddy" was chosen because this software helps with the tedious, mundane tasks of serving the Web, and is also a single place for multiple things to be organized together.) It soon became the first web server to use HTTPS automatically and by default, and now has hundreds of contributors and has served trillions of HTTPS requests.

**The name "Caddy" is trademarked.** The name of the software is "Caddy", not "Caddy Server" or "CaddyServer". Please call it "Caddy" or, if you wish to clarify, "the Caddy web server". Caddy is a registered trademark of Stack Holdings GmbH.

- _Project on X: [@caddyserver](https://x.com/caddyserver)_
- _Author on X: [@mholt6](https://x.com/mholt6)_

Caddy is a project of [ZeroSSL](https://zerossl.com), an HID Global company.

Debian package repository hosting is graciously provided by [Cloudsmith](https://cloudsmith.com). Cloudsmith is the only fully hosted, cloud-native, universal package management solution, that enables your organization to create, store and share packages in any format, to any place, with total confidence.

Caddy

Prometheus remote write proxy that adds add Cortex tenant ID header based on metric labels

# cortex-tenant

[![Go Report Card](https://goreportcard.com/badge/github.com/blind-oracle/cortex-tenant)](https://goreportcard.com/report/github.com/blind-oracle/cortex-tenant)
[![Coverage Status](https://coveralls.io/repos/github/blind-oracle/cortex-tenant/badge.svg?branch=main)](https://coveralls.io/github/blind-oracle/cortex-tenant?branch=main)
[![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/cortex-tenant)](https://artifacthub.io/packages/helm/cortex-tenant/cortex-tenant)

Prometheus/Loki remote write proxy which marks timeseries with a Cortex/Mimir/Loki tenant ID based on labels.

## Status

The project is stable and (hopefully) almost bug-free. I will accept PRs, but probably will not do any active work on it for now since I don't work with Cortex/Mimir currently.

## Architecture

![Architecture](architecture.svg)

## Overview

Cortex/Mimir/Loki tenants (separate namespaces where metrics are stored to and queried from) are identified by `X-Scope-OrgID` HTTP header on both writes and queries.

~~Problem is that Prometheus can't be configured to send this header~~ Actually in some recent version (year 2021 onwards) this functionality was added, but the tenant is the same for all jobs. This makes it impossible to use a single Prometheus (or an HA pair) to write to multiple tenants.

This software solves the problem using the following logic:

- Receive Prometheus remote write or [Loki push](https://grafana.com/docs/loki/latest/reference/loki-http-api/#ingest-logs)
- Search each timeseries/stream for a specific label name and extract a tenant ID from its value.
  For Loki the stream labels are preferred over [structured metadata](https://grafana.com/docs/loki/latest/get-started/labels/structured-metadata/) labels.
  If the label wasn't found then it can fall back to a configurable default ID.
  If none is configured then the write/push request will be rejected with HTTP code 400
- Optionally removes this label from the timeseries/stream
- Groups timeseries/streams by tenant
- Issues a number of parallel per-tenant HTTP requests to Cortex/Mimir/Loki with the relevant tenant HTTP header (`X-Scope-OrgID` by default)

## Usage

- Get `rpm` or `deb` for amd64 from the Releases page. For building see below.

### HTTP Endpoints

- GET `/alive` returns 200 by default and 503 if the service is shutting down (if `timeout_shutdown` setting is > 0)
- POST `/push` receives metrics from Prometheus - configure remote write to send here
- POST `/loki/push` receives logs from Loki - configure push to send here

### Configuration

The service can be configured by a config file and/or environment variables. Config file may be specified by passing `-config` CLI argument.

If both are used then the env vars have precedence (i.e. they override values from config).
See below for config file format and corresponding env vars.

```yaml
# Where to listen for incoming write requests from Prometheus
# env: CT_LISTEN
listen: 0.0.0.0:8080

# Profiling API, remove to disable
# env: CT_LISTEN_PPROF
listen_pprof: 0.0.0.0:7008

# Where to send the modified requests (Cortex/Mimir)
# env: CT_TARGET
target: http://127.0.0.1:9091/receive

# Where to send the modified requests (Loki)
# env: CT_TARGET_LOKI
target_loki: http://127.0.0.1:3100/loki/api/v1/push

# Whether to enable querying for IPv6 records
# env: CT_ENABLE_IPV6
enable_ipv6: false

# This parameter sets the limit for the count of outgoing concurrent connections to Cortex / Mimir.
# By default it's 64 and if all of these connections are busy you will get errors when pushing from Prometheus.
# If your `target` is a DNS name that resolves to several IPs then this will be a per-IP limit.
# env: CT_MAX_CONNS_PER_HOST
max_conns_per_host: 0

# Authentication (optional)
auth:
  # Egress HTTP basic auth -> add `Authentication` header to outgoing requests
  egress:
    # env: CT_AUTH_EGRESS_USERNAME
    username: foo
    # env: CT_AUTH_EGRESS_PASSWORD
    password: bar

# Log level
# env: CT_LOG_LEVEL
log_level: warn

# HTTP request timeout
# env: CT_TIMEOUT
timeout: 10s

# HTTP request idle timeout
# env: CT_IDLE_TIMEOUT
idle_timeout: 60s

# Timeout to wait on shutdown to allow load balancers detect that we're going away.
# During this period after the shutdown command the /alive endpoint will reply with HTTP 503.
# Set to 0s to disable.
# env: CT_TIMEOUT_SHUTDOWN
timeout_shutdown: 10s

# Max number of parallel incoming HTTP requests to handle
# env: CT_CONCURRENCY
concurrency: 10

# Whether to forward metrics metadata from Prometheus to Cortex/Mimir
# Since metadata requests have no timeseries in them - we cannot divide them into tenants
# So the metadata requests will be sent to the default tenant only, if one is not defined - they will be dropped
# env: CT_METADATA
metadata: false

# If true response codes from metrics backend will be logged to stdout. This setting can be used to suppress errors
# which can be quite verbose like 400 code - out-of-order samples or 429 on hitting ingestion limits
# Also, those are already reported by other services like Cortex/Mimir distributors and ingesters
# env: CT_LOG_RESPONSE_ERRORS
log_response_errors: true

# Maximum duration to keep outgoing connections alive (to Cortex/Mimir)
# Useful for resetting L4 load-balancer state
# Use 0 to keep them indefinitely
# env: CT_MAX_CONN_DURATION
max_connection_duration: 0s

# Address where metrics are available
# env: CT_LISTEN_METRICS_ADDRESS
listen_metrics_address: 0.0.0.0:9090

# If true, then a label with the tenant’s name will be added to the metrics
# env: CT_METRICS_INCLUDE_TENANT
metrics_include_tenant: true

tenant:
  # Which label to look for the tenant information
  # env: CT_TENANT_LABEL
  label: tenant

  # List of labels examined for tenant information. If set takes precedent over `label`
  # env: CT_TENANT_LABEL_LIST
  label_list:
    - tenant
    - other_tenant

  # Whether to remove the tenant label from the request.
  # Has no effect for Loki stream messages, they are kept as is.
  # env: CT_TENANT_LABEL_REMOVE
  label_remove: true

  # To which header to add the tenant ID
  # env: CT_TENANT_HEADER
  header: X-Scope-OrgID

  # Which tenant ID to use if the label is missing in any of the timeseries
  # If this is not set or empty then the write request with missing tenant label
  # will be rejected with HTTP code 400
  # env: CT_TENANT_DEFAULT
  default: foobar

  # Enable if you want all metrics from Prometheus to be accepted with a 204 HTTP code
  # regardless of the response from upstream. This can lose metrics if Cortex/Mimir is
  # throwing rejections.
  # env: CT_TENANT_ACCEPT_ALL
  accept_all: false

  # Optional prefix to be added to a tenant header before sending it to Cortex/Mimir.
  # Make sure to use only allowed characters:
  # https://grafana.com/docs/mimir/latest/configure/about-tenant-ids/
  # env: CT_TENANT_PREFIX
  prefix: foobar-

  # If true will use the tenant ID of the inbound request as the prefix of the new tenant id.
  # Will be automatically suffixed with a `-` character.
  # Example:
  #   Prometheus forwards metrics with `X-Scope-OrgID: Prom-A` set in the inbound request.
  #   This would result in the tenant prefix being set to `Prom-A-`.
  # https://grafana.com/docs/mimir/latest/configure/about-tenant-ids/
  # env: CT_TENANT_PREFIX_PREFER_SOURCE
  prefix_prefer_source: false
```

### Prometheus configuration example

```yaml
remote_write:
  - name: cortex_tenant
    url: http://127.0.0.1:8080/push

scrape_configs:
  - job_name: job1
    scrape_interval: 60s
    static_configs:
      - targets:
          - target1:9090
        labels:
          tenant: foobar

  - job_name: job2
    scrape_interval: 60s
    static_configs:
      - targets:
          - target2:9090
        labels:
          tenant: deadbeef
```

This would result in `job1` metrics ending up in the `foobar` tenant in Cortex/Mimir and `job2` in `deadbeef`.

## Building

`make build` should create you an _amd64_ binary.

If you want `deb` or `rpm` packages then install [FPM](https://fpm.readthedocs.io) and then run `make rpm` or `make deb` to create the packages.

## Containerization

To use the current container you need to overwrite the default configuration file, mount your configuration into to `/data/cortex-tenant.yml`.

You can overwrite the default config by starting the container with:

```bash
docker container run \
-v <CONFIG_LOCATION>:/data/cortex-tenant.yml \
ghcr.io/blind-oracle/cortex-tenant:1.6.1
```

... or build your own Docker image:

```Dockerfile
FROM ghcr.io/blind-oracle/cortex-tenant:1.6.1
ADD my-config.yml /data/cortex-tenant.yml
```

### Deploy on Kubernetes

#### Using manifests

[`deploy/k8s/manifests`](deploy/k8s/manifests) directory contains the deployment, service and configmap manifest files for deploying this on Kubernetes. You can overwrite the default config by editing the configuration parameters in the configmap manifest.

```bash
kubectl apply -f deploy/k8s/manifests/cortex-tenant-deployment.yaml
kubectl apply -f deploy/k8s/manifests/cortex-tenant-service.yaml
kubectl apply -f deploy/k8s/manifests/config-file-configmap.yml
```

#### Using a Helm Chart

[`deploy/k8s/chart`](deploy/k8s/chart) directory contains a chart for deploying this on Kubernetes.

```bash
helm repo add cortex-tenant https://blind-oracle.github.io/cortex-tenant
helm install cortex-tenant cortex-tenant/cortex-tenant
```

You can use [`deploy/k8s/chart/testing`](deploy/k8s/chart/testing) directory to test the deployment using helmfile.

```bash
helmfile -f deploy/k8s/chart/testing/helmfile.yaml template
helmfile -f deploy/k8s/chart/testing/helmfile.yaml apply
```

#### Updating chart version

```bash
helm package ./deploy/k8s/chart -d docs
TZ=UTC helm repo index ./docs
```


cortex-tenant


[![Travis Build Status](https://travis-ci.org/cortesi/devd.svg?branch=master)](https://travis-ci.org/cortesi/devd)



# devd: a local webserver for developers

![screenshot](docs/devd-terminal.png "devd in action")

# Install

Go to the [releases page](https://github.com/cortesi/devd/releases/latest), download the package for your OS, and copy the binary to somewhere on your PATH.

If you have a working Go installation, you can also say

    go install github.com/cortesi/devd/cmd/devd@latest

# Quick start

Serve the current directory, open it in the browser (**-o**), and livereload when files change (**-l**):

```bash
devd -ol .
```

Reverse proxy to http://localhost:8080, and livereload when any file in the **src** directory changes:

```bash
devd -w ./src http://localhost:8080
```


# Using devd with modd

[Modd](https://github.com/cortesi/modd) is devd's sister project - a dev tool
that runs commands and manages daemons in response to filesystem changes. Devd
can be used with modd to rebuild a project and reload the browser when
filesystem changes are detected.

Here's a quick example of a simple *modd.conf* file to illustrate.

```
src/** {
    prep: render ./src ./rendered
}

rendered/*.css ./rendered/*.html {
    daemon: devd -m ./rendered
}
```

The first block runs the *render* script whenever anything in the *src*
directory changes. The second block starts a devd instance, and triggers
livereload with a signal whenever a .css or .html file in the *rendered*
directory changes.

See the [modd](https://github.com/cortesi/modd) project page for details.


# Features

### Cross-platform and self-contained

Devd is a single statically compiled binary with no external dependencies, and
is released for macOS, Linux and Windows. Don't want to install Node or Python
in that light-weight Docker instance you're hacking in? Just copy over the devd
binary and be done with it.


### Designed for the terminal

This means no config file, no daemonization, and logs that are designed to be
read in the terminal by a developer. Logs are colorized and log entries span
multiple lines. Devd's logs are detailed, warn about corner cases that other
daemons ignore, and can optionally include things like detailed timing
information and full headers.


### Convenient

To make quickly firing up an instance as simple as possible, devd automatically
chooses an open port to run on (unless it's specified), and can open a browser
window pointing to the daemon root for you (the **-o** flag in the example
above). It also has utility features like the **-s** flag, which auto-generates
a self-signed certificate for devd, stores it in ~/.devd.certs and enables TLS
all in one step.


### Livereload

When livereload is enabled, devd injects a small script into HTML pages, just
before the closing *head* tag. The script listens for change notifications over
a websocket connection, and reloads resources as needed. No browser addon is
required, and livereload works even for reverse proxied apps. If only changes
to CSS files are seen, devd will only reload external CSS resources, otherwise
a full page reload is done. This serves the current directory with livereload
enabled:

<pre class="terminal">devd -l .</pre>

You can also trigger livereload for files that are not being served, letting
you reload reverse proxied applications when source files change. So, this
command watches the *src* directory tree, and reverse proxies to a locally
running application:

<pre class="terminal">devd -w ./src http://localhost:8888</pre>

The **-x** flag excludes files from triggering livereload based on a [pattern
specification](#excluding-files-from-livereload). The following command
disables livereload for all files with the ".less" extension:

<pre class="terminal">devd -x "**.less" -l .</pre>

When livereload is enabled (with the **-L**, **-l** or **-w** flags), devd
responds to a SIGHUP by issuing a livereload notice to all connected browsers.
This allows external tools, like devd's sister project **modd**, to trigger
livereload. If livereload is not enabled, SIGHUP causes the daemon to exit.

The closing *head* tag must be found within the first 30kb of the remote file,
otherwise livereload is disabled for the file.


### Reverse proxy + static file server + flexible routing

Modern apps tend to be collections of web servers, and devd caters for this
with flexible reverse proxying. You can use devd to overlay a set of services
on a single domain, add livereload to services that don't natively support it,
add throttling and latency simulation to existing services, and so forth.

Here's a more complicated example showing how all this ties together - it
overlays two applications and a tree of static files. Livereload is enabled for
the static files (**-l**) and also triggered whenever source files for reverse
proxied apps change (**-w**):

<pre class="terminal">
devd -l \
-w ./src/ \
/=http://localhost:8888 \
/api/=http://localhost:8889 \
/static/=./assets
</pre>

The [route specification syntax](#routes) is compact but powerful enough to cater for most use cases.

### Light-weight virtual hosting

Devd uses a dedicated domain - **localhost** - to do simple virtual hosting. This
domain and all its subdomains resolve to 127.0.0.1, which we use to set up
virtual hosting without any changes to */etc/hosts* or other local
configuration. Route specifications that don't start with a leading **/** are
taken to be subdomains of **localhost**. So, the following command serves a
static site from localhost, and reverse proxies a locally running app on
api.localhost:

<pre class="terminal">
devd ./static api=http://localhost:8888
</pre>


### Latency and bandwidth simulation

Want to know what it's like to use your fancy 5mb HTML5 app from a mobile phone
in Botswana? Look up the bandwidth and latency
[here](http://www.cisco.com/c/en/us/solutions/collateral/service-provider/global-cloud-index-gci/CloudIndex_Supplement.html),
and invoke devd like so (making sure to convert from kilobits per second to
kilobytes per second and account for the location of your server):

<pre class="terminal">devd -d 114 -u 51 -n 275 .</pre>

Devd tries to be reasonably accurate in simulating bandwidth and latency - it
uses a token bucket implementation for throttling, properly handles concurrent
requests, and chunks traffic up so data flow is smooth.


## Routes

The devd command takes one or more route specifications as arguments. Routes
have the basic format **root=endpoint**. Roots can be fixed, like
"/favicon.ico", or subtrees, like "/images/" (note the trailing slash).
Endpoints can be filesystem paths or URLs to upstream HTTP servers.

Here's a route that serves the directory *./static* under */assets* on the server:

```
/assets/=./static
```

To use a **localhost** subdomain (which will resolve to 127.0.0.1), just add it
to the the front of the root specification. We recognize subdomains by the fact
that they don't start with a leading **/**. So, this route serves the
**/static** directory under **static.localhost/assets**:

```
static/assets=./static
```

Reverse proxy specifications are similar, but the endpoint specification is a
URL. The following serves a local URL from the root **app.localhost/login**:

```
app/login=http://localhost:8888
```

If the **root** specification is omitted, it is assumed to be "/", i.e. a
pattern matching all paths. So, a simple directory specification serves the
directory tree directly under **localhost**:

```
devd ./static
```

Similarly, a simple reverse proxy can be started like this:

```
devd http://localhost:8888
```

There is also a shortcut for reverse proxying to localhost:

```
devd :8888

```

### Serving default content for files not found

The **--notfound** flag can be passed multiple times, and specifies a set of
routes that are consulted when a requested file is not found by the static file
server. The basic syntax is **root=path**, where **root** has the same
semantics as route specification. As with routes, the **root=** component is
optional, and if absent is taken to be equal to **/**. The **path** is always
relative to the static directory being served. When it starts with a leading
slash (**/**), devd will only look for a replacement file in a single location
relative to the root of the tree. Otherwise, it will search for a matching file
by joining the specified **path** with all path components up to the root of
the tree.

Let's illustrate this with an example. Say we have a */static* directory as
follows:

```
./static
├── bar
│   └── index.html
└── index.html
```

We can specify that devd should look for an *index.html* anywhere on the path
to the root of the static tree as follows:

```
devd --notfound index.html  /static
```

Now, the following happens:

* A request for */nonexistent.html* returns the contents of */index.html*
* A request for */bar/nonexistent.html* returns the contents of */bar/index.html*
* A request for */foo/bar/voing/index.html* returns the contents of */index.html*

We could instead specify an absolute path in the route, in which case the
contents of */index.html* would be returned for all the examples above:

```
devd --notfound /index.html  /static
```

Devd won't serve an over-ride page if the expected type of the incoming request
doesn't match that of the override specification. We do this by looking at the
file extension and expected MIME types of the over-ride and request, defaulting
to *text/html* if the type couldn't be positively established. This prevents
issues where, for instance, an HTML over-ride page might be served where images
are expected.


## Excluding files from livereload

The **-x** flag supports the following terms:

Term          | Meaning
------------- | -------
`*`           | matches any sequence of non-path-separators
`**`          | matches any sequence of characters, including path separators
`?`           | matches any single non-path-separator character
`[class]`     | matches any single non-path-separator character against a class of characters
`{alt1,...}`  | matches a sequence of characters if one of the comma-separated alternatives matches

Any character with a special meaning can be escaped with a backslash (`\`). Character classes support the following:

Class      | Meaning
---------- | -------
`[abc]`    | matches any single character within the set
`[a-z]`    | matches any single character in the range
`[^class]` | matches any single character which does *not* match the class


## About reverse proxying

Devd does not validate upstream SSL certificates when reverse proxying. For our
use case, development servers will usually be running locally, often with
self-signed certificates for testing. You shouldn't use devd in cases where
upstream cert validation matters.

The *X-Forwarded-Host* and *X-Forwarded-Proto* headers are set to the devd
server's address and protocol for reverse proxied traffic. You might need to
enable support for this in your application for redirects and the like to work
correctly.


# Development

The scripts used to build this package for distribution can be found
[here](https://github.com/cortesi/godist). External packages are vendored using
[dep](https://github.com/golang/dep).


devd

DudelDu
=======
DudelDu is a simple audio/video streaming server using the SHOUTcast protocol.

<p>
<a href="https://void.devt.de/pub/dudeldu/coverage.txt"><img src="https://void.devt.de/pub/dudeldu/test_result.svg" alt="Code coverage"></a>
<a href="https://goreportcard.com/report/devt.de/krotik/dudeldu">
<img src="https://goreportcard.com/badge/devt.de/krotik/dudeldu?style=flat-square" alt="Go Report Card"></a>
<a href="https://godoc.org/devt.de/krotik/dudeldu">
<img src="https://godoc.org/devt.de/krotik/dudeldu?status.svg" alt="Go Doc"></a>
</p>

Features
--------
- Supports various streaming clients: <a href="http://www.videolan.org/vlc/download-windows.en_GB.html">VLC</a>, <a href="https://play.google.com/store/apps/details?id=net.sourceforge.servestream">ServeStream</a>,  ... and most Icecast clients.
- Supports sending of meta data (sending artist and title to the streaming client).
- Playlists are simple JSON files and data files are normal media (e.g. `.mp3`, `.nsv`) files on disk.
- Can be used as a stand-alone server or embedded in other Go projects.
- Supports HTTP basic user authentication.

Getting Started (standalone application)
----------------------------------------
You can download a pre-compiled package for Windows (win64) or Linux (amd64) [here](https://void.devt.de/pub/dudeldu).

You can also pull the latest docker image of DudelDu from [Dockerhub](https://hub.docker.com/r/krotik/dudeldu):
```
docker pull krotik/dudeldu
```

Create an empty directory, change into it and run the following to start DudelDu:
```
docker run --rm --user $(id -u):$(id -g) -v $PWD:/data -p 9091:9091 krotik/dudeldu -host 0.0.0.0 <playlist>
```
The container will have access to the current local directory and all subfolders.

### Demo

DudelDu comes with a demo playlist. After extracting DudelDu switch to the directory `examples/demo`. Run ./run_demo.sh (Linux) or run_demo.bat (Windows) to start the server.

Open a browser and view the `demo.html` in the `examples/demo` directory. To access the demo streams you are prompted for a username and password. The credentials are:
```
username: web
password: web
```
You can also point your favourite audio streaming client (e.g. VLC) to the streaming URL:
```
http://localhost:9091/bach/cello_suite1
```
The demo includes also a small video in the [Nullsoft Streaming Video](https://en.wikipedia.org/wiki/Nullsoft_Streaming_Video) format (NSV). To see it point a video streaming client (e.g. VLC) to:
```
http://localhost:9091/trailer/big_buck_bunny
```
Note: By default you can only reach the streams via localhost. Use the -host parameter with a host name or IP address to expose it to external network peers.

### Command line options
The main DudelDu executable has the following command line options:
```
DudelDu x.x.x
Usage of ./dudeldu [options] <playlist>
  -?	Show this help message
  -auth string
    	Authentication as <user>:<pass>
  -debug
    	Enable extra debugging output
  -fqs int
    	Frame queue size (default 10000)
  -host string
    	Server hostname to listen on (default "127.0.0.1")
  -loop
    	Loop playlists
  -port string
    	Server port to listen on (default "9091")
  -pp string
    	Prefix all paths with a string
  -shuffle
    	Shuffle playlists
  -tps int
    	Thread pool size (default 10)

Authentication can also be defined via the environment variable: DUDELDU_AUTH="<user>:<pass>"
```

Building DudelDu
----------------
To build DudelDu from source you need to have Go installed (go >= 1.12):

Create a directory, change into it and run:
```
git clone https://devt.de/krotik/dudeldu/ .
```

You can build DudelDu's executable with:
```
go build ./server/dudeldu.go
```

Building DudelDu as Docker image
--------------------------------
DudelDu can be build as a secure and compact Docker image.

- Create a directory, change into it and run:
```
git clone https://devt.de/krotik/dudeldu/ .
```

- You can now build the Docker image with:
```
docker build --tag krotik/dudeldu .
```

License
-------
DudelDu source code is available under the [MIT License](/LICENSE).


dudeldu

A cloud native high availability/performance traffic orchestration system with observability and extensibility

# Easegress  

[![Go Report Card](https://goreportcard.com/badge/github.com/easegress-io/easegress)](https://goreportcard.com/report/github.com/easegress-io/easegress)
[![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/easegress-io/easegress/test.yml?branch=main)](https://github.com/easegress-io/easegress/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/easegress-io/easegress/branch/main/graph/badge.svg?token=5Q80B98LPI)](https://codecov.io/gh/easegress-io/easegress)
[![Docker pulls](https://img.shields.io/docker/pulls/megaease/easegress.svg)](https://hub.docker.com/r/megaease/easegress)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/easegress-io/easegress)](https://github.com/easegress-io/easegress/blob/main/go.mod)
[![Join Easegress Slack](https://img.shields.io/badge/slack-megaease-brightgreen?logo=slack)](https://cloud-native.slack.com/messages/easegress)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8265/badge)](https://www.bestpractices.dev/projects/8265)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Feasegress-io%2Feasegress.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Feasegress-io%2Feasegress?ref=badge_shield)

<a href="https://megaease.com/easegress">
    <img src="./docs/imgs/easegress.svg"
        alt="Easegress logo" title="Easegress" height="175" width="175" align="right"/>
</a>

- [What is Easegress](#what-is-easegress)
- [Features](#features)
- [Getting Started](#getting-started)
  - [Launch Easegress](#launch-easegress)
  - [Reverse Proxy](#reverse-proxy)
- [Use Cases](#use-cases)
- [Documentation](#documentation)
- [Easegress Portal](#easegress-portal)
  - [Screenshots](#screenshots)
- [Community](#community)
- [Contributing](#contributing)
- [License](#license)

## What is Easegress

`Easegress` is a Cloud Native traffic orchestration system designed for:

- **High Availability:** Built-in Raft consensus & leader election provides 99.99% availability.
- **Traffic Orchestration:** Simple orchestration of various filters for each traffic pipeline.
- **High Performance:** Lightweight and essential features speed up the performance.
- **Observability:** There are many meaningful statistics periodically in a readable way.
- **Extensibility:** It's easy to develop your own filter or controller with high-level programming language.
- **Integration:** The simple interfaces make it easy to integrate with other systems, such as Kubernetes Ingress, [EaseMesh](https://github.com/megaease/easemesh) sidecar, Workflow, etc.

The architecture of Easegress:

![architecture](./docs/imgs/architecture.png)

And you can check [Easegress DeepWiki Page](https://deepwiki.com/easegress-io/easegress) to dive into more details.

## Features

- **Service Management**
  - **Multiple protocols:**
    - HTTP/1.1
    - HTTP/2
    - HTTP/3(QUIC)
    - MQTT
  - **Rich Routing Rules:** exact path, path prefix, regular expression of the path, method, headers, clientIPs.
  - **Resilience&Fault Tolerance**
    - **CircuitBreaker:** temporarily blocks possible failures.
    - **RateLimiter:** limits the rate of incoming requests.
    - **Retry:** repeats failed executions.
    - **TimeLimiter:** limits the duration of execution.
  - **Deployment Management**
    - **Blue-green Strategy:** switches traffic at one time.
    - **Canary Strategy:** schedules traffic slightly.
  - **API Management**
    - **API Aggregation:** aggregates results of multiple APIs.
    - **API Orchestration:** orchestrates the flow of APIs.
  - **Security**
    - **IP Filter:** Limits access to IP addresses.
    - **Static HTTPS:** static certificate files.
    - **API Signature:** supports [HMAC](https://en.wikipedia.org/wiki/HMAC) verification.
    - **JWT Verification:** verifies [JWT Token](https://jwt.io/).
    - **OAuth2:** validates [OAuth/2](https://datatracker.ietf.org/doc/html/rfc6749) requests.
    - **Let's Encrypt:** automatically manage certificate files.
  - **Pipeline-Filter Mechanism**
    - **Filter Management:** makes it easy to develop new filters.
  - **Service Mesh**
    - **Mesh Master:** is the control plane to manage the lifecycle of mesh services.
    - **Mesh Sidecar:** is the data plane as the endpoint to do traffic interception and routing.
    - **Mesh Ingress Controller:** is the mesh-specific ingress controller to route external traffic to mesh services.
        > Notes: This feature is leveraged by [EaseMesh](https://github.com/megaease/easemesh)
  - **Third-Part Integration**
    - **FaaS** integrates with the serverless platform Knative.
    - **Service Discovery** integrates with Eureka, Consul, Etcd, and Zookeeper.
    - **Ingress Controller** integrates with Kubernetes as an ingress controller.
- **Extensibility**
  - **WebAssembly** executes user developed [WebAssembly](https://webassembly.org/) code.
- **High Performance and Availability**
  - **Adaption**: adapts request, response in the handling chain.
  - **Validation**: headers validation, OAuth2, JWT, and HMAC verification.
  - **Load Balance:** round-robin, random, weighted random, IP hash, header hash and support sticky sessions.
  - **Cache:** for the backend servers.
  - **Compression:** compresses body for the response.
  - **Hot-Update:** updates both config and binary of Easegress in place without losing connections.
- **Operation**
  - **Easy to Integrate:** command line([egctl](docs/02.Tutorials/2.1.egctl-Usage.md)), Easegress Portal, HTTP clients such as curl, postman, etc.
  - **Distributed Tracing**
    - Built-in [OpenTelemetry](https://opentelemetry.io/), which provides a vendor-neutral API.
  - **Observability**
    - **Node:** role(primary, secondary), raft leader status, healthy or not, last heartbeat time, and so on
    - **Traffic:** in multi-dimension: server and backend.
      - **Throughput:** total and error statistics of request count, TPS/m1, m5, m15, and error percent, etc.
      - **Latency:** p25, p50, p75, p95, p98, p99, p999.
      - **Data Size:** request and response size.
      - **Status Codes:** HTTP status codes.
      - **TopN:** sorted by aggregated APIs(only in server dimension).
- **AI Integration**
  - **Proxy:** proxy requests to LLM providers like OpenAI, DeepSeek, Anthropic, etc.
  - **Anthropic API Adaption:** adapts requests and responses in Anthropic API to OpenAI format.
  - **Vector Database:** integrates with vector databases for caching.
  - **Monitoring:** provides insights into the performance and usage of AI models.

## Getting Started

The basic usage of Easegress is to quickly set up a proxy for the backend servers.

### Launch Easegress

Easegress can be installed from pre-built binaries or from source. For details, see [Install](docs/01.Getting-Started/1.2.Install.md).

Then we can execute the server:

```bash
$ easegress-server
2023-09-06T15:12:49.256+08:00   INFO    cluster/config.go:110   config: advertise-client-urls: ...
...
```

By default, Easegress opens ports 2379, 2380, and 2381; however, you can modify these settings along with other arguments either in the configuration file or via command-line arguments. For a complete list of arguments, please refer to the `easegress-server --help` command.

After launching successfully, we could check the status of the one-node cluster.

```bash
$ egctl get member
...

$ egctl describe member
...
```

### Reverse Proxy

Assuming you have two backend HTTP services running at `127.0.0.1:9095` and `127.0.0.1:9096`, you can initiate an HTTP proxy from port 10080 to these backends using the following command:

```bash
$ egctl create httpproxy demo --port 10080 \
  --rule="/pipeline=http://127.0.0.1:9095,http://127.0.0.1:9096"
```

Then try it:

```bash
curl -v 127.0.0.1:10080/pipeline
```

The request will be forwarded to either `127.0.0.1:9095/pipeline` or `127.0.0.1:9096/pipeline`, utilizing a round-robin load-balancing policy.

More about getting started with Easegress:

- [Quick Start](docs/01.Getting-Started/1.1.Quick-Start.md)
- [Install Easegress](docs/01.Getting-Started/1.2.Install.md)
- [Main Concepts](docs/01.Getting-Started/1.3.Concepts.md)

## Use Cases

The following examples show how to use Easegress for different scenarios.

- [API Aggregation](docs/02.Tutorials/2.3.Pipeline-Explained.md#api-aggregation) - Aggregating many APIs into a single API.
- [Cluster Deployment](docs/05.Administration/5.1.Config-and-Cluster-Deployment.md) - How to deploy multiple Easegress cluster nodes.
- [Canary Release](docs/03.Advanced-Cookbook/3.04.Canary-Release.md) - How to do canary release with Easegress.
- [Distributed Tracing](docs/03.Advanced-Cookbook/3.05.Distributed-Tracing.md) - How to do APM tracing  - Zipkin.
- [FaaS](docs/03.Advanced-Cookbook/3.09.FaaS.md) - Supporting Knative FaaS integration
- [Flash Sale](docs/03.Advanced-Cookbook/3.09.FaaS.md) - How to do high concurrent promotion sales with Easegress
- [Kubernetes Ingress Controller](docs/04.Cloud-Native/4.1.Kubernetes-Ingress-Controller.md) - How to integrate with Kubernetes as ingress controller
- [LoadBalancer](docs/02.Tutorials/2.3.Pipeline-Explained.md#load-balancer) - A number of the strategies of load balancing
- [MQTTProxy](docs/03.Advanced-Cookbook/3.01.MQTT-Proxy.md) - An Example to MQTT proxy with Kafka backend.
- [Multiple API Orchestration](docs/03.Advanced-Cookbook/3.03.Multiple-API-Orchestration.md) - An Telegram translation bot.
- [Performance](docs/03.Advanced-Cookbook/3.11.Performance.md) - Performance optimization - compression, caching etc.
- [Pipeline](docs/02.Tutorials/2.3.Pipeline-Explained.md) - How to orchestrate HTTP filters for requests/responses handling
- [Resilience and Fault Tolerance](docs/02.Tutorials/2.4.Resilience.md) - CircuitBreaker, RateLimiter, Retry, TimeLimiter, etc. (Porting from [Java resilience4j](https://github.com/resilience4j/resilience4j))
- [Security](docs/02.Tutorials/2.5.Traffic-Verification.md) - How to do authentication by Header, JWT, HMAC, OAuth2, etc.
- [Service Registry](docs/03.Advanced-Cookbook/3.06.Service-Registry.md) - Supporting the Microservice registries - Zookeeper, Eureka, Consul, Nacos, etc.
- [WebAssembly](docs/03.Advanced-Cookbook/3.07.WasmHost.md) - Using AssemblyScript to extend the Easegress
- [WebSocket](docs/02.Tutorials/2.6.Websocket.md) - WebSocket proxy for Easegress
- [Workflow](docs/03.Advanced-Cookbook/3.10.Workflow.md) - An Example to make a workflow for a number of APIs.

For full list, see [Tutorials](docs/02.Tutorials/README.md) and [Cookbook](docs/03.Advanced-Cookbook/README.md).

## Documentation

- [Getting Started](docs/01.Getting-Started/README.md)
- [Tutorials](docs/02.Tutorials/README.md)
- [Advanced Cookbook](docs/03.Advanced-Cookbook/README.md)
- [Cloud Native](docs/04.Cloud-Native/README.md)
- [Administration](docs/05.Administration/README.md)
- [Development](docs/06.Development-for-Easegress/README.md)
- [Reference](docs/07.Reference/README.md)

## Easegress Portal

[Easegress Portal](https://github.com/easegress-io/easegress-portal) is an intuitive, open-source user interface for the Easegress traffic orchestration system. Developed with React.js, this portal provides config management, metrics, and visualizations, enhancing the overall Easegress experience.

### Screenshots

**1. Cluster Management**

![cluster](./docs/imgs/portal/cluster.png)

**2. Traffic Management**

![traffic http server](./docs/imgs/portal/traffic-http-server.png)

**3. Pipeline Management**

![pipeline detail](./docs/imgs/portal/pipeline-detail.png)

## Community

- [Join Slack Workspace](https://cloud-native.slack.com/messages/easegress) for requirement, issue and development.
- [MegaEase on Twitter](https://twitter.com/megaease)

### Community Tools

- [KubeStellar Console Guided Install](https://console.kubestellar.io/missions/install-easegress) - Step-by-step guided installation with pre-flight checks, validation, troubleshooting, and rollback.

## Contributing

See [Contributing guide](./CONTRIBUTING.md#contributing). The project welcomes contributions and suggestions that abide by the [CNCF Code of Conduct](./CODE_OF_CONDUCT.md).

## License

Easegress is under the Apache 2.0 license. See the [LICENSE](./LICENSE) file for details.

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Feasegress-io%2Feasegress.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Feasegress-io%2Feasegress?ref=badge_large)

Easegress

Highly-available key value store for shared configuration and service discovery

# etcd

[![Go Report Card](https://goreportcard.com/badge/github.com/etcd-io/etcd?style=flat-square)](https://goreportcard.com/report/github.com/etcd-io/etcd)
[![Coverage](https://codecov.io/gh/etcd-io/etcd/branch/main/graph/badge.svg)](https://app.codecov.io/gh/etcd-io/etcd/tree/main)
[![Tests](https://github.com/etcd-io/etcd/actions/workflows/tests.yaml/badge.svg)](https://github.com/etcd-io/etcd/actions/workflows/tests.yaml)
[![codeql-analysis](https://github.com/etcd-io/etcd/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/etcd-io/etcd/actions/workflows/codeql-analysis.yml)
[![Docs](https://img.shields.io/badge/docs-latest-green.svg)](https://etcd.io/docs)
[![Godoc](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](https://godocs.io/go.etcd.io/etcd/v3)
[![Releases](https://img.shields.io/github/release/etcd-io/etcd/all.svg?style=flat-square)](https://github.com/etcd-io/etcd/releases)
[![LICENSE](https://img.shields.io/github/license/etcd-io/etcd.svg?style=flat-square)](https://github.com/etcd-io/etcd/blob/main/LICENSE)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/etcd-io/etcd/badge)](https://scorecard.dev/viewer/?uri=github.com/etcd-io/etcd)

**Note**: The `main` branch may be in an *unstable or even broken state* during development. For stable versions, see [releases][github-release].

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cncf/artwork/9870640f123303a355611065195c43ac3f27aa19/projects/etcd/horizontal/white/etcd-horizontal-white.png">
  <source media="(prefers-color-scheme: light)" srcset="logos/etcd-horizontal-color.svg">
  <img alt="etcd logo" src="logos/etcd-horizontal-color.svg" width=269 />
</picture>

etcd is a distributed reliable key-value store for the most critical data of a distributed system, with a focus on being:

* *Simple*: well-defined, user-facing API (gRPC)
* *Secure*: automatic TLS with optional client cert authentication
* *Fast*: benchmarked 10,000 writes/sec
* *Reliable*: properly distributed using Raft

etcd is written in Go and uses the [Raft][] consensus algorithm to manage a highly-available replicated log.

etcd is used [in production by many companies](./ADOPTERS.md), and the development team stands behind it in critical deployment scenarios, where etcd is frequently teamed with applications such as [Kubernetes][k8s], [locksmith][], [vulcand][], [Doorman][], and many others. Reliability is further ensured by rigorous [**robustness testing**](https://github.com/etcd-io/etcd/tree/main/tests/robustness).

See [etcdctl][etcdctl] for a simple command line client.

![etcd reliability is important](logos/etcd-xkcd-2347.png)

<sub>Original image credited to  xkcd.com/2347, alterations by Josh Berkus.</sub>

[raft]: https://raft.github.io/
[k8s]: http://kubernetes.io/
[doorman]: https://github.com/youtube/doorman
[locksmith]: https://github.com/coreos/locksmith
[vulcand]: https://github.com/vulcand/vulcand
[etcdctl]: https://github.com/etcd-io/etcd/tree/main/etcdctl

## Documentation

The most common API documentation you'll need can be found here:

* [go.etcd.io/etcd/api/v3](https://godocs.io/go.etcd.io/etcd/api/v3)
* [go.etcd.io/etcd/client/pkg/v3](https://godocs.io/go.etcd.io/etcd/client/pkg/v3)
* [go.etcd.io/etcd/client/v3](https://godocs.io/go.etcd.io/etcd/client/v3)
* [go.etcd.io/etcd/etcdctl/v3](https://godocs.io/go.etcd.io/etcd/etcdctl/v3)
* [go.etcd.io/etcd/pkg/v3](https://godocs.io/go.etcd.io/etcd/pkg/v3)
* [go.etcd.io/etcd/raft/v3](https://godocs.io/go.etcd.io/etcd/raft/v3)
* [go.etcd.io/etcd/server/v3](https://godocs.io/go.etcd.io/etcd/server/v3)

## Maintainers

[Maintainers](OWNERS) strive to shape an inclusive open source project culture where users are heard and contributors feel respected and empowered. Maintainers aim to build productive relationships across different companies and disciplines. Read more about [Maintainers role and responsibilities](Documentation/contributor-guide/community-membership.md#maintainers).

## Getting started

### Getting etcd

The easiest way to get etcd is to use one of the pre-built release binaries which are available for OSX, Linux, Windows, and Docker on the [release page][github-release].

For more installation guides, please check out [play.etcd.io](http://play.etcd.io) and [operating etcd](https://etcd.io/docs/latest/op-guide).

[github-release]: https://github.com/etcd-io/etcd/releases

### Running etcd

First start a single-member cluster of etcd.

If etcd is installed using the [pre-built release binaries][github-release], run it from the installation location as below:

```bash
/tmp/etcd-download-test/etcd
```

The etcd command can be simply run as such if it is moved to the system path as below:

```bash
mv /tmp/etcd-download-test/etcd /usr/local/bin/
etcd
```

This will bring up etcd listening on port 2379 for client communication and on port 2380 for server-to-server communication.

Next, let's set a single key, and then retrieve it:

```bash
etcdctl put mykey "this is awesome"
etcdctl get mykey
```

etcd is now running and serving client requests. For more, please check out:

* [Interactive etcd playground](http://play.etcd.io)
* [Animated quick demo](https://etcd.io/docs/latest/demo)

### etcd TCP ports

The [official etcd ports][iana-ports] are 2379 for client requests, and 2380 for peer communication.

[iana-ports]: http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt

### Running a local etcd cluster

First install [goreman](https://github.com/mattn/goreman), which manages Procfile-based applications.

Our [Procfile script](./Procfile) will set up a local example cluster. Start it with:

```bash
goreman start
```

This will bring up 3 etcd members `infra1`, `infra2` and `infra3` and optionally etcd `grpc-proxy`, which runs locally and composes a cluster.

Every cluster member and proxy accepts key value reads and key value writes.

Follow the comments in [Procfile script](./Procfile) to add a learner node to the cluster.

### Install etcd client v3

```bash
go get go.etcd.io/etcd/client/v3
```

### Next steps

Now it's time to dig into the full etcd API and other guides.

* Read the full [documentation].
* Review etcd [frequently asked questions].
* Explore the full gRPC [API].
* Set up a [multi-machine cluster][clustering].
* Learn the [config format, env variables and flags][configuration].
* Find [language bindings and tools][integrations].
* Use TLS to [secure an etcd cluster][security].
* [Tune etcd][tuning].

[documentation]: https://etcd.io/docs/latest
[api]: https://etcd.io/docs/latest/learning/api
[clustering]: https://etcd.io/docs/latest/op-guide/clustering
[configuration]: https://etcd.io/docs/latest/op-guide/configuration
[integrations]: https://etcd.io/docs/latest/integrations
[security]: https://etcd.io/docs/latest/op-guide/security
[tuning]: https://etcd.io/docs/latest/tuning

## Contact

* Email: [etcd-dev](https://groups.google.com/g/etcd-dev)
* Slack: [#sig-etcd](https://kubernetes.slack.com/archives/C3HD8ARJ5) channel on Kubernetes ([get an invite](http://slack.kubernetes.io/))
* [Community meetings](#community-meetings)

### Community meetings

etcd contributors and maintainers meet every week at `11:00` AM (USA Pacific) on Thursday and meetings alternate between community meetings and issue triage meetings. Meeting agendas are recorded in a [shared Google doc][shared-meeting-notes] and everyone is welcome to suggest additional topics or other agendas.

Issue triage meetings are aimed at getting through our backlog of PRs and Issues. Triage meetings are open to any contributor; you don't have to be a reviewer or approver to help out! They can also be a good way to get started contributing.

The meeting lead role is rotated for each meeting between etcd maintainers or sig-etcd leads and is recorded in a [shared Google sheet][shared-rotation-sheet].

Meeting recordings are uploaded to the official etcd [YouTube channel].

Get calendar invitations by joining [etcd-dev](https://groups.google.com/g/etcd-dev) mailing group.

Join the CNCF-funded Zoom channel: [zoom.us/my/cncfetcdproject](https://zoom.us/my/cncfetcdproject)

[shared-meeting-notes]: https://docs.google.com/document/d/16XEGyPBisZvmmoIHSZzv__LoyOeluC5a4x353CX0SIM/edit
[shared-rotation-sheet]: https://docs.google.com/spreadsheets/d/1jodHIO7Dk2VWTs1IRnfMFaRktS9IH8XRyifOnPdSY8I/edit
[YouTube channel]: https://www.youtube.com/@etcdio

## Contributing

See [CONTRIBUTING](CONTRIBUTING.md) for details on setting up your development environment, submitting patches and the contribution workflow.

Please refer to [community-membership.md](Documentation/contributor-guide/community-membership.md#member) for information on becoming an etcd project member.  We welcome and look forward to your contributions to the project!

Please also refer to [roadmap](Documentation/contributor-guide/roadmap.md) to get more details on the priorities for the next few major or minor releases.

## Reporting bugs

See [reporting bugs](https://github.com/etcd-io/etcd/blob/main/Documentation/contributor-guide/reporting_bugs.md) for details about reporting any issues. Before opening an issue please check it is not covered in our [frequently asked questions].

[frequently asked questions]: https://etcd.io/docs/latest/faq

## Reporting a security vulnerability

See [security disclosure and release process](security/README.md) for details on how to report a security vulnerability and how the etcd team manages it.

## Issue and PR management

See [issue triage guidelines](https://github.com/etcd-io/etcd/blob/main/Documentation/contributor-guide/triage_issues.md) for details on how issues are managed.

See [PR management](https://github.com/etcd-io/etcd/blob/main/Documentation/contributor-guide/triage_prs.md) for guidelines on how pull requests are managed.

## etcd Emeritus Maintainers

etcd [emeritus maintainers](OWNERS) dedicated a part of their career to etcd and reviewed code, triaged bugs and pushed the project forward over a substantial period of time. Their contribution is greatly appreciated.

### License

etcd is under the Apache 2.0 license. See the [LICENSE](LICENSE) file for details.


etcd

Self-hosted music streaming server with built-in web UI and REST API

Euterpe
======

<img src="images/heavy-metal-128.png" alt="Euterpe Icon" align="left" style="margin-right: 20px" title="Euterpe Icon" />

Euterpe is self-hosted streaming service for music.

A way to listen to your music library from everywhere. Once set up you won't need anything but a browser. Think of it as your own Spotify service over which you have full control. Euterpe will let you browse through and listen to your music over HTTP(s). Up until now I've had a really bad time listening to my music which is stored back home. I would create a mount over ftp, sshfs or something similar and point the local player to the mounted library. Every time it resulted in some unpleasantry. Just imagine searching in a network mounted directory!

No more!

[![Build Status](https://github.com/ironsmile/euterpe/actions/workflows/build-test-lint.yml/badge.svg?branch=master)](https://github.com/ironsmile/euterpe/actions/workflows/build-test-lint.yml?query=branch%3Amaster) [![GoDoc](https://pkg.go.dev/badge/github.com/ironsmile/euterpe)](https://godoc.org/github.com/ironsmile/euterpe) [![Go Report Card](https://goreportcard.com/badge/github.com/ironsmile/euterpe)](https://goreportcard.com/report/github.com/ironsmile/euterpe) [![Coverage Status](https://coveralls.io/repos/github/ironsmile/euterpe/badge.svg?branch=master)](https://coveralls.io/github/ironsmile/euterpe?branch=master)

* [Web UI](#web-ui)
* [Features](#features)
* [Demo](#demo)
* [Requirements](#requirements)
* [Install](#install)
* [Docker Image](#docker)
* [Configuration](#configuration)
* [As an API](#as-an-api)
* [OSX Media Keys Control](#media-keys-control-for-osx)
* [Clients](#clients)
* [Change Log](CHANGELOG.md)
* [Name Change](#name-change)


Web UI
======

Have a taste of how its web interface looks like

![Euterpe Screenshot](images/euterpe-preview.webp)

It comes with a custom [jPlayer](https://github.com/happyworm/jPlayer) which can handle playlists with thousands of songs. Which is [an improvement](https://github.com/jplayer/jPlayer/pull/192) over the original which never included this performance patch.

I feel obliged to say that the music on the screenshot is written and performed by my close friend [Velislav Ivanov](http://www.progarchives.com/artist.asp?id=4264).


Features
======

* Simple. It is just one binary, that's it! You don't need to faff about with interpreters or web servers
* Fast. A typical response time on my more than a decade old mediocre computer is 26ms for a fairly large collection
* Supports the most common audio formats such as mp3, oga, ogg, wav, flac, opus, web and m4a audio formats
* Built-in fast and simple Web UI so that you can play your music on every device
* Media and UI could be served over HTTP(S) natively without the need for other software
* User authentication (HTTP Basic, query token, Bearer token)
* Media artwork from local files or automatically downloaded from the [Cover Art Archive](https://musicbrainz.org/doc/Cover_Art_Archive)
* Artist images could be downloaded automatically from [Discogs](https://www.discogs.com/)
* Search by track name, artist or album
* Download whole album in a zip file with one click
* Controllable via media keys in OSX with the help of [BeardedSpice](https://beardedspice.github.io/)
* Extensible via [stable API](#as-an-api)
* Multiple [clients and player plugins](#clients)
* Uses [jplayer](https://github.com/happyworm/jPlayer) to play your music on really old browsers

Demo
======

Just show, don't talk, will ya? I will! You may take the server a spin with the [live demo](https://listen-to-euterpe.eu/demo) if you would like to. Feel free to thank all the artists who made their music available for this!

Requirements
======
If you want to install it from source you will need:

* [Go](http://golang.org/) 1.24 or later [installed and properly configured](http://golang.org/doc/install).

* [taglib](https://taglib.org/) - Read the [install instructions](https://github.com/taglib/taglib/blob/master/INSTALL.md) or better yet the one inside your downloaded version. Most operating systems will have it in their package manager, though. Better use this one.

* [International Components for Unicode](http://site.icu-project.org/) - The Euterpe binary dynamically links to `libicu`. Your friendly Linux distribution probably already has a package. For other OSs one should [go here](http://site.icu-project.org/download).

Install
======

The safest route is installing [one of the releases](https://github.com/ironsmile/euterpe/releases).

#### Linux & macOS

If you have [one of the releases](https://github.com/ironsmile/euterpe/releases) (for example `euterpe_1.1.0_linux.tar.gz`) it includes an `install` script which would install Euterpe in `/usr/bin/euterpe`. You will have to uninstall any previously installed versions first. An `uninstall` script is provided as well.

#### Windows

Automatically creating a release version for Windows is in progress at the moment. For the time being check out the next section, "From Source". Pay attention to the [requirements](#requirements) section above. As of writing this the author hasn't been yet initiated in the secret art of building and installing libraries on Windows so you are on your own.

#### From Source (any OS)

If installing from source running `go install` in the project root directory will compile `euterpe` and move its binary in your `$GOPATH`. Releases from `v1.0.1` onward have their go dependencies vendored in.

So, to install the `master` branch, you can just run

```
go install github.com/ironsmile/euterpe
```

Or alternatively, if you want to produce a release version you will have to get the repository. Then in the root of the project run

```
make release
```

This will produce a binary `euterpe` which is ready for distribution. Check its version with

```
./euterpe -v
```

First Run
======

Once installed, you are ready to use your media server. After its initial run it will create a configuration file which you will have to edit to suit your needs.

1. Start it with ```euterpe```

2. [Edit the config.json](#configuration) and add your library paths to the "library" field. This is an *important* step. Without it, `euterpe` will not know where your media files are.


Docker
======

Alternatively to installing everything in your environment you can use the [Docker image](https://hub.docker.com/r/ironsmile/euterpe).

Start the server by running:

```sh
docker run -v "${HOME}/Music/:/root/Music" -p 8080:9996 -d ironsmile/euterpe:latest euterpe
```

Then point your browser to [https://localhost:8080](https://localhost:8080) and you will see the Euterpe web UI. The `-v` flag in the Docker command will mount your `$HOME/Music` directory to be discoverable by Euterpe.


### Building the Image Yourself

You can use the [Dockerfile](Dockerfile) in this repository to build the image yourself.

```docker build -t ironsmile/euterpe github.com/ironsmile/euterpe```

The `euterpe` binary there is placed in `/usr/local/bin/euterpe`.

Configuration
======

HTTPS configuration is saved in a JSON file, different for every user in the system. Its
location is as follows:

* Linux or BSD: ```$HOME/.euterpe/config.json```
* Windows: ```%APPDATA%\euterpe\config.json```

When started for the first time Euterpe will create one for you. Here is an example:

```js
{
    // Address and port on which Euterpe will listen. It is in the form hostname[:port]
    // For exact explanation see the Addr field in the Go's net.http.Server
    // Make sure the user running Euterpe have permission to bind on the specified
    // port number
    "listen": ":443",

    // true if you want to access Euterpe over HTTPS or false for plain HTTP.
    // If set to true the "ssl_certificate" field must be configured as well.
    "ssl": true,

    // Provides the paths to the certificate and key files. Must be full paths, not
    // relatives. If "ssl" is false this can be left out.
    "ssl_certificate": {
        "crt": "/full/path/to/certificate/file.crt",
        "key": "/full/path/to/key/file.key"
    },

    // true if you want the server to require HTTP basic authentication. Credentials
    // are set by the 'authentication' field below.
    "basic_authenticate": true,
    
    // User and password for the HTTP basic authentication.
    "authentication": {
        "user": "example",
        "password": "example"
    },

    // An array with all the directories which will be scanned for media. They must be
    // full paths and formatted according to your OS. So for example a Windows path
    // have to be something like "D:\Media\Music".
    // As expected Euterpe will need permission to read in the library folders.
    "libraries": [
        "/path/to/my/files",
        "/some/more/files/can/be/found/here"
    ],
    
    // Optional configuration on how to scan libraries. Note that this configuration
    // is applied to each library separately.
    "library_scan": {
        // Will wait this much time before actually starting to scan a library.
        // This might be useful when scanning is resource hungry operation and you
        // want to postpone it on start up.
        "initial_wait_duration": "1s",
        
        // With this option a "operation" is defined by this number of scanned files.
        "files_per_operation": 1500,

        // After each "operation", sleep this amount of time.
        "sleep_after_operation": "15ms"
    },

    // When true, Euterpe will search for images on the internet. This means album artwork
    // and artists images. Cover Art Archive is used for album artworks when none is
    // found locally. And Discogs for artist images. Anything found will be saved in
    // the Euterpe database and later used to prevent further calls to the archive.
    "download_artwork": true,

    // If download_artwork is true the server will try to find artist artwork in the
    // Discogs database. In order for this to work an authentication is required
    // with their API. This here must be a personal access token. In effect the server
    // will make requests on your behalf.
    //
    // See the API docs for more information:
    // https://www.discogs.com/developers/#page:authentication,header:authentication-discogs-auth-flow
    "discogs_auth_token": "some-personal-token",

    // If set to true, logs will include a line for every HTTP request handled by the
    // server.
    "access_log": false
}
```

List with all directives can be found in the [configuration wiki](https://github.com/ironsmile/euterpe/wiki/configuration#wiki-json-directives).

As an API
======

Check out the Euterpe API reference for:

* For the current branch at [API.md](API.md)
* The latest released Eupterpe version at the [website's docs](https://listen-to-euterpe.eu/docs/api/).

Media Keys Control For OSX
======

You can control your Euterpe web interface with the media keys the same way you can control any native media player. To achieve this a third-party program is required: [BearderSpice](https://beardedspice.github.io/). Sadly, Euterpe is [not included](https://github.com/beardedspice/beardedspice/pull/684) in the default web strategies bundled-in with the program. You will have to import the [strategy](https://github.com/beardedspice/beardedspice/tree/disco-strategy-web#writing-a-media-strategy) [file](tools/bearded-spice.js) included in this repo yourself.

How to do it:

1. Install BeardedSpice. Here's the [download link](https://beardedspice.github.io/#download)
2. Then go to BeardedSpice's Preferences -> General -> Media Controls -> Import
3. Select the [bearded-spice.js](tools/bearded-spice.js) strategy from this repo

Or with images:

BeardedSpice Preferences:

![BS Install Step 1](images/barded-spice-install-step1.png)

Select "Import" under General tab:

![BS Install Step 2](images/barded-spice-install-step2.png)

Select the [bearded-spice.js](tools/bearded-spice.js) file:

![BS Install Step 3](images/barded-spice-install-step3.png)

Then you are good to go. Smash those media buttons!


Clients
======

You are not restricted to using the web UI. The server has a RESTful API which can easily be used from other clients. I will try to keep a list with all of the known clients here:

* ~~[httpms-android](https://github.com/ironsmile/httpms-android) is a Android client for HTTPMS.~~ Long abandoned in favour of a React Native mobile client.
* [euterpe-mobile](https://github.com/ironsmile/euterpe-mobile) is an iOS/Android mobile client written with React Native.
* [euterpe-rhythmbox](https://github.com/ironsmile/euterpe-rhythmbox) is an Euterpe client plug-in for Gnome's Rhythmbox.
* [euterpe-gtk](https://github.com/ironsmile/euterpe-gtk) is a GTK client for mobile or desktop.


Euterpe

Fider is an open platform to collect and organize customer feedback


<p align="center">
  <a href="https://fider.io/" target="_blank">
    <img src="etc/fiderlogo.png" width="300" alt="Fider">
  </a>
</p>

<p align="center">
    <a href="https://fider.io/">Fider.io</a> •
    <a href="https://feedback.fider.io">Fider Feedback</a> •
    <a href="https://demo.fider.io">Fider Demo</a> •
    <a href="https://docs.fider.io">Docs</a> •
    <a href="https://github.com/TryGhost/Ghost/blob/main/.github/CONTRIBUTING.md">Contributing</a>
</p>

<br/>
<br/>

<img src="etc/fidergithub.png">

<br/>
<br/>

[![build](https://github.com/getfider/fider/actions/workflows/build.yml/badge.svg)](https://github.com/getfider/fider/actions/workflows/build.yml)

# Fider is a feedback portal for feature requests and suggestions.

__Give your customers a voice and let them tell you what they need. Spend less time guessing and more time building the right product.__

# Getting Started

## ☁️ **Fider Cloud**

The easiest and quickest way to get started. A fully managed services by the creators of Fider to help you get started in minutes. Forget about managing software updates and patches, we do it all for you! [Sign up now](https://fider.io/#get-started)

## 🏢 **Self-Hosted**

Install Fider on your own servers, in your own infrastructure. It's totally free, but of course you're responsible for everything. [Learn how](https://docs.fider.io/self-hosted/)

If you do self-host and enjoy Fider, please [let us know where you're using it](https://github.com/getfider/fider/issues/899) - we really appreciate it 🙏

# 💰 Donations and Sponsors

Support the development of Fider to help us make it the best feedback tool! You can set up donations as small or large as you want to help us keep Fider going. [Donate](https://opencollective.com/fider)

If your organization uses Fider, consider becoming a sponsor - set up a monthly donation and get your logo and link on the README. [Become a sponsor](https://opencollective.com/fider)

<br/>
<br/>

# Contributors

This project exists thanks to all the amazing people who contribute!

<a href="https://github.com/getfider/fider/graphs/contributors"><img src="https://opencollective.com/fider/contributors.svg?width=890&button=false" /></a>

Read our [CONTRIBUTING](CONTRIBUTING.md) guide to learn how you can contribute to Fider.

<br/>
<br/>


Fider

Flagr is an open-source feature flagging and A/B testing service

<p align="center">
    <a href="https://github.com/openflagr/flagr/actions/workflows/ci.yml?query=branch%3Amain+" target="_blank">
        <img src="https://github.com/openflagr/flagr/actions/workflows/ci.yml/badge.svg?branch=main">
    </a>
    <a href="https://goreportcard.com/report/github.com/openflagr/flagr" target="_blank">
        <img src="https://goreportcard.com/badge/github.com/openflagr/flagr">
    </a>
    <a href="https://godoc.org/github.com/openflagr/flagr" target="_blank">
        <img src="https://img.shields.io/badge/godoc-reference-green.svg">
    </a>
    <a href="https://github.com/openflagr/flagr/releases" target="_blank">
        <img src="https://img.shields.io/github/release/openflagr/flagr.svg?style=flat&color=green">
    </a>
    <a href="https://codecov.io/gh/openflagr/flagr">
        <img src="https://codecov.io/gh/openflagr/flagr/branch/main/graph/badge.svg?token=iwjv26grrN">
    </a>
    <a href="https://deepwiki.com/openflagr/flagr">
        <img src="https://deepwiki.com/badge.svg?color=green" alt="Ask DeepWiki">
    </a>
</p>

## Introduction

`openflagr/flagr` is a community-driven OSS effort of advancing the development of Flagr.

Flagr is an open source Go service that delivers the right experience to the right entity and monitors the impact. It provides feature flags, experimentation (A/B testing), and dynamic configuration. It has clear swagger REST APIs for flags management and flag evaluation.

## Documentation

- https://openflagr.github.io/flagr

## Quick demo

Try it with Docker.

```sh
# Start the docker container
docker pull ghcr.io/openflagr/flagr
docker run -it -p 18000:18000 ghcr.io/openflagr/flagr

# Open the Flagr UI
open localhost:18000
```

Or try it on [https://try-flagr.onrender.com](https://try-flagr.onrender.com),
it may take a while for a cold start, and every commit to the `main` branch will trigger
a redeployment of the demo website.

```
curl --request POST \
     --url https://try-flagr.onrender.com/api/v1/evaluation \
     --header 'content-type: application/json' \
     --data '{
       "entityID": "127",
       "entityType": "user",
       "entityContext": {
         "state": "NY"
       },
       "flagID": 1,
       "enableDebug": true
     }'
```

## Flagr Evaluation Performance

Tested with `vegeta`. For more details, see [benchmarks](./benchmark).

```
Requests      [total, rate]            56521, 2000.04
Duration      [total, attack, wait]    28.2603654s, 28.259999871s, 365.529µs
Latencies     [mean, 50, 95, 99, max]  371.632µs, 327.991µs, 614.918µs, 1.385568ms, 12.50012ms
Bytes In      [total, mean]            23250552, 411.36
Bytes Out     [total, mean]            8308587, 147.00
Success       [ratio]                  100.00%
Status Codes  [code:count]             200:56521
Error Set:
```

## Flagr UI

<p align="center">
    <img src="./docs/images/demo_readme.png" width="900">
</p>

## Client Libraries

| Language   | Clients                                         |
| ---------- | ----------------------------------------------- |
| Go         | [goflagr](https://github.com/openflagr/goflagr) |
| Javascript | [jsflagr](https://github.com/openflagr/jsflagr) |
| Python     | [pyflagr](https://github.com/openflagr/pyflagr) |
| Ruby       | [rbflagr](https://github.com/openflagr/rbflagr) |

## License and Credit

- [`openflagr/flagr`](https://github.com/openflagr/flagr) Apache 2.0
- [`checkr/flagr`](https://github.com/checkr/flagr) Apache 2.0


Flagr

A self contained feature flag solution written in Go and Vue.js

<img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=dc285028-90ba-436b-9a4a-e0d826a2c986" alt="" />

<p align=center>
    <img src="logo.svg" alt="Flipt" width=275 height=96 />
</p>

<p align="center">The Git-native, enterprise-ready feature management platform that developers love</p>

<hr />

<p align="center">
    <img src=".github/images/dashboard.png" alt="Flipt Dashboard" width=600 />
</p>

<br clear="both"/>

<div align="center">
    
    <img src="https://img.shields.io/badge/status-stable-green" alt="Flipt v2 Stable" />
    <a href="https://goreportcard.com/report/github.com/flipt-io/flipt">
        <img src="https://goreportcard.com/badge/github.com/flipt-io/flipt" alt="Go Report Card" />
    </a>
    <a href="https://github.com/avelino/awesome-go">
        <img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Go" />
    </a>
    <a href="https://flipt.io/discord">
        <img alt="Discord" src="https://img.shields.io/discord/960634591000014878?color=%238440f1&label=Discord&logo=discord&logoColor=%238440f1&style=flat" />
    </a>
    <a href="https://deepwiki.com/flipt-io/flipt">
      <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
    </a>
</div>

<div align="center">
    <h4>
        <a href="https://docs.flipt.io/v2/introduction">Docs</a> •
        <a href="http://www.flipt.io">Website</a> •
        <a href="http://blog.flipt.io">Blog</a> •
        <a href="#contributing">Contributing</a> •
        <a href="https://www.flipt.io/discord">Discord</a>
    </h4>
</div>

> [!NOTE]  
> **Looking for Flipt v1?** You can find the v1 code on the [`main` branch](https://github.com/flipt-io/flipt/tree/main) and documentation at [docs.flipt.io](https://docs.flipt.io/).

## Why Flipt v2?

**Finally, feature flags that work with your existing Git workflow.**

Flipt v2 is the first truly Git-native feature management platform that treats your feature flags as code. Store your flags in your own Git repositories, use your existing branching strategy, and deploy flags alongside your code using the tools you already know and trust.

### 🚀 **Git-Native by Design**

- **Own your data**: Store feature flags directly in your Git repositories
- **Version control**: Full history and blame for every flag change
- **Branch and merge**: Test flag changes in branches before merging to production
- **Deploy together**: Feature flags deploy with your code using existing CI/CD pipelines

### 🌍 **Multi-Environment with Git Flexibility**

- **Environment per branch**: Map environments to Git branches for seamless workflows  
- **Environment per directory**: Organize flags by microservice or team within a single repo
- **Environment per repository**: Separate repos for different products or security domains
- **Complete isolation**: Each environment has its own namespaces, flags, and configurations

### ⚡ **Developer Experience First**

- **Zero infrastructure**: No databases, no external dependencies by default
- **GitOps ready**: Works with existing Git-based deployment workflows
- **Real-time updates**: Server-Sent Events (SSE) streaming API for instant flag propagation to client-side SDKs without polling
- **Modern UI**: Intuitive interface with full Git integration and dark mode support

### 🔒 **Enterprise Security & Control**

- **Self-hosted**: Keep sensitive flag data within your infrastructure
- **Secrets management**: Secure storage and retrieval of sensitive configuration data (OSS)
- **GPG commit signing**: Cryptographically sign all flag changes for enhanced security (Pro feature)
- **Merge proposals**: Code review workflow for flag changes (Pro feature)
- **Audit trails**: Complete history of who changed what and when
- **OIDC/JWT/OAuth**: Enterprise authentication methods supported

<br clear="both"/>

## Flipt v1 vs v2: What's New?

| Feature | Flipt v1 | ✨ Flipt v2 |
|---------|----------|----------|
| **Storage** | Database-centric (MySQL, PostgreSQL, SQLite) | Git-native with optional SCM sync (GitHub, GitLab, BitBucket, Azure DevOps, Gitea, etc.) |
| **Environments** | Single namespace model | Multi-environment with Git flexibility |
| **Branching** | Not supported | Full Git branching with environment branches |
| **Data Ownership** | Stored in a database (MySQL, PostgreSQL, SQLite) | Stored in your Git repositories alongside your code |
| **GitOps** | Read-only Git integration | Full read/write Git integration |
| **Deployment** | Requires database setup | Zero dependencies - single binary |
| **Version Control** | Basic audit logs | Full Git history and blame |
| **Merge Process** | Direct flag changes | Merge proposals with code review |
| **Real-time Updates** | Polling required | Server-Sent Events (SSE) streaming API for instant updates |
| **Multi-tenancy** | Manual namespace management | Environment-based isolation |
| **Secrets Management** | None | File-based providers available in OSS, HashiCorp Vault, cloud secrets management (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault) available in Pro |

<br clear="both"/>

## Use Cases

Perfect for engineering teams that want to:

- **Ship faster with confidence**: Deploy flags with your code using existing Git workflows
- **Enable trunk-based development**: Merge incomplete features behind flags without risk
- **Implement proper GitOps**: Treat infrastructure and feature flags as code
- **Maintain security compliance**: Keep sensitive flag data within your infrastructure  
- **Scale with multiple environments**: Manage flags across dev, staging, and production seamlessly
- **Enable team collaboration**: Use familiar Git workflows for flag reviews and approvals

<br clear="both"/>

## Quick Start

See our [quickstart guide](https://docs.flipt.io/v2/quickstart) for more details.

### Local

```bash
# Install Flipt
curl -fsSL https://get.flipt.io/v2 | sh

# Wizard-driven setup to get you started quickly
flipt quickstart

# Run Flipt server
flipt server
```

### Docker

```bash
docker run --rm -p 8080:8080 -p 9000:9000 -t docker.flipt.io/flipt/flipt:v2
```

Flipt UI will be available at [http://127.0.0.1:8080/](http://127.0.0.1:8080).

#### Nightly Builds

> [!WARNING]  
> Nightly builds are automatically generated from the latest v2 branch and should not be considered stable for production use.

To run the latest nightly build:

```bash
docker run --rm -p 8080:8080 -p 9000:9000 -t docker.flipt.io/flipt/flipt:v2-nightly
```

Nightly builds include the latest features and bug fixes but may contain untested changes. Use them for testing new features or verifying bug fixes before the next stable release.

### Configuration Example

```yaml
# config.yml - Git-native setup with secrets management
secrets:
  providers:
    # File-based secrets (OSS)
    file:
      enabled: true
      base_path: "/etc/flipt/secrets"
    # HashiCorp Vault (Pro feature)
    vault:
      enabled: true
      address: "https://vault.example.com"
      auth_method: "token"
      token: "hvs.your_token"
      mount: "secret"

storage:
  type: git
  git:
    repository: "https://github.com/your-org/feature-flags.git"
    ref: "main"
    poll_interval: "30s"
    signature:
      enabled: true
      type: "gpg"
      key_ref:
        provider: "vault"  # Requires Pro license
        path: "flipt/signing-key"
        key: "private_key"
      name: "Flipt Bot"
      email: "bot@example.com"

environments:
  default:
    storage: git
  staging:
    storage: git
    directory: "staging"
```

For more setup options, see our [configuration documentation](https://docs.flipt.io/v2/configuration/overview).

<br clear="both"/>

## Core Values

- 🔒 **Security** - HTTPS, OIDC, JWT, OAuth, K8s Service Token, and API Token authentication methods supported out of the box
- 🗝️ **Secrets Management** - Secure storage and retrieval of sensitive data with file-based providers (OSS) and HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault (Pro features)
- 🎛️ **Control** - Your data stays in your Git repositories within your infrastructure  
- 🚀 **Speed** - Co-located with your services, no external API calls required
- ✅ **Simplicity** - Single binary with no external dependencies by default
- 🔄 **GitOps Ready** - Native Git integration that works with your existing workflows
- 👍 **Compatibility** - GRPC, REST, Redis, Prometheus, ClickHouse, OpenTelemetry, and more

<br clear="both"/>

## Key Features

### Git-Native Storage

- Store flags directly in Git repositories alongside your code
- Full version control with Git history, blame, and diff support  
- Integrates with your SCM (GitHub, GitLab, BitBucket, Azure DevOps, Gitea, etc.)
- GPG commit signing for cryptographic verification of changes

### Multi-Environment Management  

- Environment per Git branch, directory, or repository
- Complete environment isolation with independent configurations
- Seamless environment promotion workflows

### Secrets Management & Security

- **Multi-provider secrets management**: File-based providers available in OSS, HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, and Azure Key Vault (Pro features)
- **GPG Commit Signing**: Cryptographically sign all flag changes with keys from secret providers (Pro feature)
- **Secure key storage**: Private keys and sensitive data stored securely in Vault or local files
- **Multiple auth methods**: Token, Kubernetes, and AppRole authentication for Vault

### Advanced Flag Management

- Complex targeting rules and user segmentation
- Percentage-based rollouts
- Real-time flag evaluation with Server-Sent Events (SSE) streaming updates for instant synchronization

### Developer Experience

- Modern UI with Git integration and dark mode 🌙
- Declarative flag configuration with JSON/YAML schemas
- Comprehensive REST and gRPC APIs

### Enterprise & Security Features

- **Authentication**: OIDC, JWT, OAuth, and more authentication methods supported out of the box
- **Observability**: OpenTelemetry and Prometheus integration 🔋
- **Secrets Management**: File-based providers (OSS) with HashiCorp Vault integration available in Pro
- **Enterprise Workflows**: GPG commit signing, merge proposals, and DevOps integration available in Pro

> **Ready for enterprise features?** Flipt v2 Pro includes advanced workflows, enhanced security, and dedicated support. Get started with a **free 14-day trial** – no credit card required.
>
> **[Learn More About Pro Features →](https://docs.flipt.io/v2/pro)**

Are we missing a feature that you'd like to see? [Let us know by opening an issue!](https://github.com/flipt-io/flipt/issues)

<br clear="both"/>

## Integration & SDKs

Check out our [integration documentation](https://docs.flipt.io/v2/integration/overview) for comprehensive guides.

### Server-Side Evaluation

- **REST API** - Full HTTP API for any language
- **gRPC API** - High-performance binary protocol

### Client-Side Evaluation  

- **Local evaluation** - Reduce latency with client-side flag evaluation, evaluate flags within your application for extreme speed and reliability.

### OpenFeature Integration

Flipt supports the [OpenFeature](https://openfeature.dev/) standard for vendor-neutral feature flag evaluation, including the emerging OpenFeature Remote Evaluation Protocol (OFREP) for standardized remote flag evaluation.

<br clear="both"/>

## Contributing

We would love your help! Before submitting a PR, please read over the [Contributing](CONTRIBUTING.md) guide.

No contribution is too small, whether it be bug reports/fixes, feature requests, documentation updates, or anything else that can help drive the project forward.

Not sure how to get started? You can:

- Join our [Discord](https://www.flipt.io/discord), and ask any questions there
- Dive into any of the open issues, here are some examples:
  - [Good First Issues](https://github.com/flipt-io/flipt/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
  - [Backend](https://github.com/flipt-io/flipt/issues?q=is%3Aissue+is%3Aopen+label%3Ago)
  - [Frontend](https://github.com/flipt-io/flipt/issues?q=is%3Aopen+is%3Aissue+label%3Aui)

Review the [Development](DEVELOPMENT.md) documentation for more information on how to contribute to Flipt.

<br clear="both"/>

## Flipt v2 Pro

Ready to unlock the full potential of Git-native feature management? Flipt v2 Pro adds enterprise-grade features on top of our solid open-source foundation.

### What's Included in Pro

- **🔀 Enterprise DevOps Integration** - Native GitHub, GitLab, BitBucket, Azure DevOps, and Gitea workflows with merge proposals and automated PR/MR creation
- **✍️ GPG Commit Signing** - Cryptographically sign all changes for maximum security and auditability with verified commit badges
- **🔒 Integrated Secrets Management** - Built-in secure storage for GPG keys with HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, and Azure Key Vault integration
- **🌐 Air-Gapped Environment Support** - Annual licenses work seamlessly in air-gapped environments with offline validation
- **🏢 Dedicated Support Channel** - Direct access to our engineering team via dedicated Slack channel for faster issue resolution
- **⚡ Priority Development** - Your bug reports and feature requests get prioritized
- **🔧 Enterprise Auth** - Advanced authentication providers (🔄 coming soon)
- **📊 Advanced Analytics** - Enhanced reporting and insights (🔄 coming soon)

### Pricing & Trial

- **Free 14-day trial** - No credit card required to start, includes all Pro features
- **Monthly licenses** - $200/month with continuous internet connectivity for validation
- **Annual licenses** - $2,000/year (save $400) with offline validation using license files for air-gapped environments
- **No instance limits** on paid plans - run Flipt v2 Pro on as many servers as you need
- **Cancel anytime** - Prorated billing through our Stripe customer portal

**[Start Your Free 14-Day Trial →](https://docs.flipt.io/v2/pro#getting-started)**

*Trial includes up to 5 instances. Upgrade seamlessly to unlimited instances with a paid subscription.*

<br clear="both"/>

## Community

For help and discussion around Flipt, feature flag best practices, and more, join us on [Discord](https://www.flipt.io/discord).

<br clear="both"/>

<p align="center">
    <a href="https://www.producthunt.com/posts/flipt-cloud?embed=true&utm_source=badge-featured&utm_medium=badge&utm_souce=badge-flipt&#0045;cloud" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=498373&theme=light" alt="Flipt&#0032;Cloud - Feature&#0032;flags&#0046;&#0032;Powered&#0032;by&#0032;Git | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
    <a href="https://devhunt.org/tool/flipt" title="DevHunt - Tool of the Week"><img src="./.github/images/devhunt-badge.png" width=225 alt="DevHunt - Tool of the Week" /></a>&nbsp;
    <a href="https://console.dev/tools/flipt" title="Visit Console - the best tools for developers"><img src="./.github/images/console-badge.png" width=250 alt="Console - Developer Tool of the Week" /></a>
</p>

<br clear="both"/>

## Release Cadence

Flipt follows [semantic versioning](https://semver.org/) for versioning.

We aim to release a new minor version of Flipt every 2-3 weeks. This allows us to quickly iterate on new features.
Bug fixes and security patches (patch versions) will be released as needed.

<br clear="both"/>

## Development

[Development](DEVELOPMENT.md) documentation is available for those interested in contributing to Flipt.

We welcome contributions of any kind, including but not limited to bug fixes, feature requests, documentation improvements, and more. Just open an issue or pull request and we'll be happy to help out!

<br clear="both"/>

## Licensing

There are currently two types of licenses in place for Flipt:

1. Client License  
2. Server License

### Client License

All of the code required to generate GRPC clients in other languages as well as the [Go SDK](/sdk/go) are licensed under the [MIT License](https://spdx.org/licenses/MIT.html).

This code exists in the [rpc/](rpc/) directory.

The client code is the code that you would integrate into your applications, which is why a more permissive license is used.

### Server License

The server code is licensed under the [Fair Core License, Version 1.0, MIT Future License](https://github.com/flipt-io/flipt/blob/v2/LICENSE).

See our [licensing docs](https://docs.flipt.io/v2/licensing) and [fcl.dev](https://fcl.dev) for more information.

flipt

A simple, complete and lightweight self-hosted feature flag solution 100% Open Source

go-feature-flag

Simple Reverse Proxy with Caching, written in Go, using Redis

# Go Proxy Cache

<center>

![Logo](https://github.com/fabiocicerchia/go-proxy-cache/raw/main/docs/assets/logo_small.png)

Simple Reverse Proxy with Caching, written in Go, using Redis.  
    >>> **(semi) production-ready** <<<

[![MIT License](https://img.shields.io/badge/License-MIT-brightgreen.svg?longCache=true)](LICENSE)
[![Pull Requests](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?longCache=true)](https://github.com/fabiocicerchia/go-proxy-cache/pulls)
![Maintenance](https://img.shields.io/maintenance/yes/2023)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)  
  
![Last Commit](https://img.shields.io/github/last-commit/fabiocicerchia/go-proxy-cache)
![Release Date](https://img.shields.io/github/release-date/fabiocicerchia/go-proxy-cache)
![GitHub all releases](https://img.shields.io/github/downloads/fabiocicerchia/go-proxy-cache/total)

![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/fabiocicerchia/go-proxy-cache)
![GitHub release (latest by date)](https://img.shields.io/github/v/release/fabiocicerchia/go-proxy-cache)

![Docker pulls](https://img.shields.io/docker/pulls/fabiocicerchia/go-proxy-cache "Docker pulls")
![Docker stars](https://img.shields.io/docker/stars/fabiocicerchia/go-proxy-cache "Docker stars")

![GitHub Workflow Status](https://img.shields.io/github/workflow/status/fabiocicerchia/go-proxy-cache/Builds)

[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4469/badge)](https://bestpractices.coreinfrastructure.org/projects/4469)
[![BCH compliance](https://bettercodehub.com/edge/badge/fabiocicerchia/go-proxy-cache?branch=main)](https://bettercodehub.com/results/fabiocicerchia/go-proxy-cache)
[![Go Report Card](https://goreportcard.com/badge/github.com/fabiocicerchia/go-proxy-cache)](https://goreportcard.com/report/github.com/fabiocicerchia/go-proxy-cache)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Ffabiocicerchia%2Fgo-proxy-cache.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Ffabiocicerchia%2Fgo-proxy-cache?ref=badge_shield)  
[![codecov](https://codecov.io/gh/fabiocicerchia/go-proxy-cache/branch/main/graph/badge.svg)](https://codecov.io/gh/fabiocicerchia/go-proxy-cache)
[![Maintainability](https://img.shields.io/codeclimate/maintainability/fabiocicerchia/go-proxy-cache)](https://codeclimate.com/github/fabiocicerchia/go-proxy-cache/maintainability)
[![Technical Debt](https://img.shields.io/codeclimate/tech-debt/fabiocicerchia/go-proxy-cache)](https://codeclimate.com/github/fabiocicerchia/go-proxy-cache/maintainability)
[![Total alerts](https://img.shields.io/lgtm/alerts/g/fabiocicerchia/go-proxy-cache.svg)](https://lgtm.com/projects/g/fabiocicerchia/go-proxy-cache/alerts/)

</center>

---

## 💗 Support the Project 💗

This project is only maintained by one person, [Fabio Cicerchia](https://github.com/fabiocicerchia).  
It started as a simple caching service, now it has a lot of pro functionalities just for FREE 😎  
Maintaining a project is a very time consuming activity, especially when done alone 💪
I really want to make this project better and become super cool 🚀

Two commercial versions have been planned: [PRO and PREMIUM](https://kodebeat.com/goproxycache.html).  

The development of the COMMUNITY version will continue, but priority will be given to the [COMMERCIAL versions](https://kodebeat.com/goproxycache.html).  
- If you'd like to support this open-source project I'll appreciate any kind of [contribution](https://github.com/sponsors/fabiocicerchia).
- If you'd like to sponsor the commercial version, please [get in touch with me](mail:info@fabiocicerchia.it).

---

## How it works

When the request is cached:

```text
        .---------.       .---------.       .---------.
        |         |       |         |       |         |
        |         |       |         |       |         |
you --->|---->----|--->---|---->----|--->---|-->--.   |
        |         |       |         |       |     |   |
    <---|----<----|---<---|----<----|---<---|--<--'   |
        `---------´       `---------´       `---------´
          network        go-proxy-cache        redis
```

When the request is not cached:

```text
          website
            ,_,
            | |
        .---+-+---.       .---------.       .---------.
        |   | '-->|--->---|---->----|--->---|-->--,   |
        |   '-<---|---<---|<--,     |       |     |   |
        |         |       |   |     |       |     |   |
you --->|---->----|--->---|---'     |       |     |   |
        |         |       |         |       |     |   |
    <---|----<----|---<---|----<----|---<---|--<--'   |
        `---------´       `---------´       `---------´
          network        go-proxy-cache        redis
```

## Features

### Small, Pragmatic and Easy to Use

- **Dockerized**
- **Compiled**
- **Easily Configurable**, via YAML or Environment Variables.
- **Self-Contained**, does not require Go, Git or any other software installed. Just run the binary or the container.

### Caching

- **Full Page Caching**, via Redis.
- **Cache Invalidation**, by calling HTTP Method `PURGE` on the resource URI.
- **Cache Bypass**, by using the HTTP Header `X-Go-Proxy-Cache-Force-Fresh` the request will always be fresh.
- **Support Chunking**, by replicating exactly the same original amount.
- **Selective HTTP Status Codes/Methods**, allows caching for different response codes or HTTP methods.
- **ETag Support**, generating non-weak tags, handling `304 Not Modified`, managing HTTP headers `If-Modified-Since`, `If-Unmodified-Since`, `If-None-Match`, `If-Match`.  
  ETag wrapper doesn't work well with WebSocket and HTTP/2.
- **Cache Stampede Prevention**, delaying invalidation request to the backend using an extra small random TTL (between 5s and 10s).
- **Serving Stale Content**, used mainly for avoiding cache stampede, for maximum 10s.
- **Upstream DNS Resolution Cache**, the upstream hostname will be cached to speed up the response and avoid the DNS resolution at each request.

### Load Balancing

- **HTTP & HTTPS Forward Traffic**
- **Load Balancing**, uses a list of IPs/Hostnames as load balanced backend servers.
- **Multiple Algorithms Available**, choose among IP Hash, Least Connections, Random or Round-Robin.
- **Support for HTTP Basic Auth**, it's possible to provide the HTTP Basic Auth for each endpoint (by specify user:pass in the URL).

### Security

- **HTTP/2 Support**, HTTP/2 Pusher achievable only if upstream implements [HTTP header `Link`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Link). Server Push is deprecated (since not really supported in the browsers).
- **SSL/TLS Certificates via ACME**, provides automatic generation of SSL/TLS certificates from [Let's Encrypt](https://letsencrypt.org/) and any other ACME-based CA.
- **Using your own SSL/TLS Certificates**, optional.

### Reliability

- **Healthcheck Endpoint**, exposes the route `/healthcheck` (internally).
- **Upstream Healthcheck**, verifies periodically if upstream nodes are healthy.
- **Respecting HTTP Cache Headers**, `Vary`, `ETag`, `Cache-Control` and `Expires`.
- **Fully Tested**, Unit, Functional & Linted & 0 Race Conditions Detected.
- **Cache Circuit Breaker**, bypassing Redis when not available.

### Scaling

- **Multiple domains**, override and fine-tune the global settings per domain.

### Customisations

- **HTTP to HTTPS Redirects**, optional, status code to be used when redirecting HTTP to HTTPS.
- **GZip Compression**, optional.
- **Server Timeouts**, it is possible to configure in details the server overall timeouts (read, write, headers, handler, idle).
- **Fine tuning circuit-breaker and TLS settings**, it is possible to adjust the settings about thresholds, timeouts and failure rate.
- **Configure error handler**, stdout or file.
- **Debug/Verbose mode**, it is possible to have additional levels of details by settings the flags `-verbose` or `-debug`.

### Logging

- **Request Tracing**, each line in logs has a RequestID to easily identify the response flow.
- **OpenTelemetry Tracing**, each request has a deep tracing with Jaeger (optional).
- **Prometheus Endpoint**, exposes the route `/metrics` (internally) to serve Prometheus metrics.
- **Support for Sentry & Syslog**, all warning/error logs can be forwarded to Sentry and/or Syslog.

## Configuration

## YAML

This is a simple (and not comprehensive) configuration:

```yaml
server:
  port:
    http: "80"
    https: "443"
  tls:
    cert_file: server.pem
    key_file: server.key
  upstream:
    host: ~
    port: 443
    scheme: https
    endpoints:
      - 127.0.0.1
    http_to_https: true
    redirect_status_code: 301

cache:
  hosts: 
    - localhost:6379

domains:
  example_com:
    server:
      upstream:
        host: example.com

  example_org:
    server:
      upstream:
        host: example.org
```

For more details about the full server configuration check the relative documentation in [docs/CONFIGURATION.md](https://github.com/fabiocicerchia/go-proxy-cache/blob/main/docs/CONFIGURATION.md)

## Examples

## CLI

```console
$ go-proxy-cache -h
Usage of go-proxy-cache:
  -config string
        config file (default "config.yml")
  -debug
        enable debug
  -log string
        log file (default stdout)
  -test
        test configuration
  -verbose
        enable verbose
  -version
        display version
[...]
```

For examples check the relative documentation in [docs/EXAMPLES.md](https://github.com/fabiocicerchia/go-proxy-cache/blob/main/docs/EXAMPLES.md)

## Release Cycle

- Bug-fixes (e.g. `1.1.1`, `1.1.2`, `1.2.1`, `1.2.3`) are released as needed (no additional features are delivered in those versions, bug-fixes only).
- Each version is supported until the next one is released (e.g. `1.1.x` will be supported until `1.2.0` is out).
- We use [Semantic Versioning](https://semver.org/).

## Common Errors

- `acme/autocert: server name component count invalid`  
  Let's Encrypt cannot be used locally, as described in [this thread](https://community.letsencrypt.org/t/can-i-test-lets-encrypt-client-on-localhost/15627)
- `acme/autocert: missing certificate`  
  Let's Encrypt cannot be used locally, as described in [this thread](https://community.letsencrypt.org/t/can-i-test-lets-encrypt-client-on-localhost/15627)
- `501 Not Implemented`  
  If there's no domain defined in the main configuration nor in the domain overrides, and a client will request an
  unknown domain the status `501` is returned.
- WebSocket and TimeoutHandler are not working together, because TimeoutHandler doesn't support Hijacker, so in order to have WebSocket support the setting `TimeoutHandler` must be set to `-1`.
- `context deadline exceeded`  
  The reason is because the timeout on the context.Context of the client side of the request is shorter than the timeout
  in the server side handler. This means that the client gives up before any response is written.

## References

- [Proxy servers and tunneling](https://developer.mozilla.org/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling)
- [Make resilient Go net/http servers using timeouts, deadlines and context cancellation](https://ieftimov.com/post/make-resilient-golang-net-http-servers-using-timeouts-deadlines-context-cancellation/)
- [So you want to expose Go on the Internet](https://blog.cloudflare.com/exposing-go-on-the-internet/)
- [Writing a very fast cache service with millions of entries in Go](https://allegro.tech/2016/03/writing-fast-cache-service-in-go.html)
- [RFC7234 - Hypertext Transfer Protocol (HTTP/1.1): Caching](https://tools.ietf.org/html/rfc7234#section-4.2.1)
- [The complete guide to Go net/http timeouts](https://blog.cloudflare.com/the-complete-guide-to-golang-net-http-timeouts/)
- [What Happens in a TLS Handshake? | SSL Handshake](https://www.cloudflare.com/en-gb/learning/ssl/what-happens-in-a-tls-handshake/)
- [A step by step guide to mTLS in Go](https://venilnoronha.io/a-step-by-step-guide-to-mtls-in-go)
- [Learning HTTP caching in Go](https://www.sanarias.com/blog/115LearningHTTPcachinginGo)
- [Nginx HTTP2 Server Push](https://ops.tips/blog/nginx-http2-server-push/)
- [Introducing HTTP/2 Server Push with NGINX 1.13.9](https://www.nginx.com/blog/nginx-1-13-9-http2-server-push)
- [Preload - W3C Editor's Draft 20 August 2020](https://w3c.github.io/preload/#server-push)
- [Web Linking](https://tools.ietf.org/html/rfc5988)
- [HTTP Health Checks](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/)
- [Types of load balancing algorithms](https://www.cloudflare.com/en-gb/learning/performance/types-of-load-balancing-algorithms/)

## License

## OpenSSL

This product includes software developed by the OpenSSL Project for use in the
OpenSSL Toolkit. ([http://www.openssl.org/](http://www.openssl.org/))

## Go Proxy Cache

MIT License

Copyright (c) 2023 Fabio Cicerchia <info@fabiocicerchia.it>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Ffabiocicerchia%2Fgo-proxy-cache.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Ffabiocicerchia%2Fgo-proxy-cache?ref=badge_large)


go-proxy-cache

Reverse proxy for handle https with issue certificates in fly from lets-encrypt

[![Build Status](https://travis-ci.org/rekby/lets-proxy2.svg?branch=master)](https://travis-ci.org/rekby/lets-proxy2)
[![Coverage Status](https://coveralls.io/repos/github/rekby/lets-proxy2/badge.svg?branch=master)](https://coveralls.io/github/rekby/lets-proxy2?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/rekby/lets-proxy2)](https://goreportcard.com/report/github.com/rekby/lets-proxy2)
[![GolangCI](https://golangci.com/badges/github.com/rekby/lets-proxy2.svg)](https://golangci.com/r/github.com/rekby/lets-proxy2)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)  


Русскоязычное описание ниже (Russian below).

English description
===================
Home page: https://github.com/rekby/lets-proxy2

Features:
* Domain names for certificates get from request by [SNI]([url](https://en.wikipedia.org/wiki/Server_Name_Indication))
* http-01 and tls-alpn-01 validation
* HTTPS (with certificate autoissue) and HTTP reverse proxy
* Zero config for start usage
* Time limit for issue certificate
* Auto include subdomains in certificate (default: domain and www.domain)
* Logging for stderr and/or file
* Self rotate log files (can disable by config)
* Can configure backend in dependence of incoming connection IP:Port
* Custom headers to backend
* Self check domain before issue cert (prevent DoS cert issue attack by requests with bad domains)
* Blacklist/whitelist of domains
* Lock certificates (force to use manual issued certificate without internal checks)
* Optional access to internal metrics with Prometheus format

It is next generation of https://github.com/rekby/lets-proxy, rewrited from scratch.

It is improove logging and internal structure for better test coverage and simpler support.
Add config support instead of many command line flags.

A reverse-proxy server to handle https requests transparently. By default Lets-proxy handles
https requests to port 443 and proxies them as http to port 80 on the same IP address.

Lets-proxy adds the http headers, `X-Forwarded-For` which contains the IP address.
It obtains valid TLS certificates from Let's Encrypt and handles https for free, in an automated way, 
including certificate renewal, and without warning in browsers. It needs only for domain be true public domain and has A/AAAA record to public available IP address.

The program was created for shared hosting and can handle many thousands of domains per server.
It is simple to implement and doesn't need settings to start the program on personal server/vps.

Quick start:

    ./lets-proxy or lets-proxy.exe
    
Use --help key for details:

    ./lets-proxy --help or lets-proxy.exe --help

Русский (Russian):
==================
Сайт программы: https://github.com/rekby/lets-proxy2

Возможности:
* Доменные имена для выпуска сертификатов получаются из [SNI]([url](https://ru.wikipedia.org/wiki/Server_Name_Indication)), их не нужно настраивать.
* Авторизация доменов по протоколам http-01 and tls-alpn-01
* Проксирование HTTPS (с автовыпуском сертификата) and HTTP
* Начать использование можно без настроек
* Ограничение времени на получение сертификата
* Автоматическое получение сертификата для домена и поддоменов (default: domain and www.domain)
* Вывод логов в файл и/или на стандартный вывод ошибок
* Самостоятельная ротация лог-файлов (отключается в настройках)
* Можно настроить адрес перенаправления запроса в заивисмости от адреса приема запроса.
* Настраиваемые дополнительные заголовки для передачи на внутренний сервер
* Самостоятельная проверка возможности выпуска сертификата перед его запросом (для исключения DoS-атак путем запросов с неправильными доменами)
* Белый/чёрный списки доменов для выпуска сертификатов
* Фиксированный сертификат (возможность использовать самостоятельно полученный сертификат, без внутренних проверок и автообновления)
* Опциональный доступ к внутренним метрикам в формате Prometheus


Эта программа - следующая итерация после https://github.com/rekby/lets-proxy, переписанная с нуля.

Улучшено логирование, внутреннее устройство кода - для упрощения тестирования и поддержки/развития.
Добавлена поддержка файла настроек вместо огромного списка флагов.

Реверс-прокси сервер для прозрачной обработки https-запросов. Для начала использования достаточно просто запустить его на сервере с 
запущенным http-сервером. При этом lets-proxy начнёт слушать порт 433 и передавать запросы на порт 80 с тем же IP-адресом.
К запросу будет добавляться заголовок `X-Forwarded-For` с IP-адресом источника запроса.
Сертификаты для работы https получаются в реальном времени от letsencrypt.org. Это правильные
(не самоподписанные) бесплатные сертификаты, которым доверяют браузеры. Нужно только чтобы домен был общедоступен и указывал на общедоступный IP-адрес.

Программа разрабатывается для использования на виртуальном хостинге и может работать с тысячами доменов
на каждом сервере.
С другой стороны она проста и не требует начальных настроек для запуска на персональном сервере.

Быстрый старт:

    ./lets-proxy или lets-proxy.exe


Used libraries (alphabet ordered):
==================================

* http://github.com/gojuno/minimock - for tests
* http://github.com/kardianos/minwinsvc - for run as windows service
* http://github.com/maxatome/go-testdeep - for tests
* http://github.com/mitchellh/gox - for multiply binaries build
* http://github.com/pelletier/go-toml - for config file.
* http://github.com/rekby/zapcontext - for pass logger to/from context
* http://github.com/satori/go.uuid - for generate uuid
* http://go.uber.org/zap - for logging
* http://golang.org/x/crypto - use acme part - for access for lets encrypt server.
* http://golang.org/x/net - use idna part for log domain names
* http://gopkg.in/natefinch/lumberjack.v2 - use for self log rotation.


lets-proxy2

Minio is a distributed object storage server

> [!NOTE]
> **THIS REPOSITORY IS NO LONGER MAINTAINED.**
>
> **Alternatives:**
> - **[AIStor Free](https://min.io/download)** — Full-featured, standalone edition for community use (free license)
> - **[AIStor Enterprise](https://min.io/pricing)** — Distributed edition with commercial support

---

# MinIO Quickstart Guide

[![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) [![Docker Pulls](https://img.shields.io/docker/pulls/minio/minio.svg?maxAge=604800)](https://hub.docker.com/r/minio/minio/) [![license](https://img.shields.io/badge/license-AGPL%20V3-blue)](https://github.com/minio/minio/blob/master/LICENSE)

[![MinIO](https://raw.githubusercontent.com/minio/minio/master/.github/logo.svg?sanitize=true)](https://min.io)

MinIO is a high-performance, S3-compatible object storage solution released under the GNU AGPL v3.0 license.
Designed for speed and scalability, it powers AI/ML, analytics, and data-intensive workloads with industry-leading performance.

- S3 API Compatible – Seamless integration with existing S3 tools
- Built for AI & Analytics – Optimized for large-scale data pipelines
- High Performance – Ideal for demanding storage workloads.

This README provides instructions for building MinIO from source and deploying onto baremetal hardware.
Use the [MinIO Documentation](https://github.com/minio/docs) project to build and host a local copy of the documentation.

## MinIO is Open Source Software

We designed MinIO as Open Source software for the Open Source software community. We encourage the community to remix, redesign, and reshare MinIO under the terms of the AGPLv3 license.

All usage of MinIO in your application stack requires validation against AGPLv3 obligations, which include but are not limited to the release of modified code to the community from which you have benefited. Any commercial/proprietary usage of the AGPLv3 software, including repackaging or reselling services/features, is done at your own risk.

The AGPLv3 provides no obligation by any party to support, maintain, or warranty the original or any modified work.
All support is provided on a best-effort basis through Github and our [Slack](https://slack.min.io) channel, and any member of the community is welcome to contribute and assist others in their usage of the software.

MinIO [AIStor](https://www.min.io/product/aistor) includes enterprise-grade support and licensing for workloads which require commercial or proprietary usage and production-level SLA/SLO-backed support. For more information, [reach out for a quote](https://min.io/pricing).

## Source-Only Distribution

**Important:** The MinIO community edition is now distributed as source code only. We will no longer provide pre-compiled binary releases for the community version.

### Installing Latest MinIO Community Edition

To use MinIO community edition, you have two options:

1. **Install from source** using `go install github.com/minio/minio@latest` (recommended)
2. **Build a Docker image** from the provided Dockerfile

See the sections below for detailed instructions on each method.

### Legacy Binary Releases

Historical pre-compiled binary releases remain available for reference but are no longer maintained:

- GitHub Releases: https://github.com/minio/minio/releases
- Direct downloads: https://dl.min.io/server/minio/release/

**These legacy binaries will not receive updates.** We strongly recommend using source builds for access to the latest features, bug fixes, and security updates.

## Install from Source

Use the following commands to compile and run a standalone MinIO server from source.
If you do not have a working Golang environment, please follow [How to install Golang](https://golang.org/doc/install). Minimum version required is [go1.24](https://golang.org/dl/#stable)

```sh
go install github.com/minio/minio@latest
```

You can alternatively run `go build` and use the `GOOS` and `GOARCH` environment variables to control the OS and architecture target.
For example:

```
env GOOS=linux GOARCH=arm64 go build
```

Start MinIO by running `minio server PATH` where `PATH` is any empty folder on your local filesystem.

The MinIO deployment starts using default root credentials `minioadmin:minioadmin`.
You can test the deployment using the MinIO Console, an embedded web-based object browser built into MinIO Server.
Point a web browser running on the host machine to <http://127.0.0.1:9000> and log in with the root credentials.
You can use the Browser to create buckets, upload objects, and browse the contents of the MinIO server.

You can also connect using any S3-compatible tool, such as the MinIO Client `mc` commandline tool:

```sh
mc alias set local http://localhost:9000 minioadmin minioadmin
mc admin info local
```

See [Test using MinIO Client `mc`](#test-using-minio-client-mc) for more information on using the `mc` commandline tool.
For application developers, see <https://docs.min.io/enterprise/aistor-object-store/developers/sdk/> to view MinIO SDKs for supported languages.

> [!NOTE]
> Production environments using compiled-from-source MinIO binaries do so at their own risk.
> The AGPLv3 license provides no warranties nor liabilities for any such usage.

## Build Docker Image

You can use the `docker build .` command to build a Docker image on your local host machine.
You must first [build MinIO](#install-from-source) and ensure the `minio` binary exists in the project root.

The following command builds the Docker image using the default `Dockerfile` in the root project directory with the repository and image tag `myminio:minio`

```sh
docker build -t myminio:minio .
```

Use `docker image ls` to confirm the image exists in your local repository.
You can run the server using standard Docker invocation:

```sh
docker run -p 9000:9000 -p 9001:9001 myminio:minio server /tmp/minio --console-address :9001
```

Complete documentation for building Docker containers, managing custom images, or loading images into orchestration platforms is out of scope for this documentation.
You can modify the `Dockerfile` and `dockerscripts/docker-entrypoint.sh` as-needed to reflect your specific image requirements.

See the [MinIO Container](https://docs.min.io/community/minio-object-store/operations/deployments/baremetal-deploy-minio-as-a-container.html#deploy-minio-container) documentation for more guidance on running MinIO within a Container image.

## Install using Helm Charts

There are two paths for installing MinIO onto Kubernetes infrastructure:

- Use the [MinIO Operator](https://github.com/minio/operator)
- Use the community-maintained [Helm charts](https://github.com/minio/minio/tree/master/helm/minio)

See the [MinIO Documentation](https://docs.min.io/community/minio-object-store/operations/deployments/kubernetes.html) for guidance on deploying using the Operator.
The Community Helm chart has instructions in the folder-level README.

## Test MinIO Connectivity

### Test using MinIO Console

MinIO Server comes with an embedded web based object browser.
Point your web browser to <http://127.0.0.1:9000> to ensure your server has started successfully.

> [!NOTE]
> MinIO runs console on random port by default, if you wish to choose a specific port use `--console-address` to pick a specific interface and port.

### Test using MinIO Client `mc`

`mc` provides a modern alternative to UNIX commands like ls, cat, cp, mirror, diff etc. It supports filesystems and Amazon S3 compatible cloud storage services.

The following commands set a local alias, validate the server information, create a bucket, copy data to that bucket, and list the contents of the bucket.

```sh
mc alias set local http://localhost:9000 minioadmin minioadmin
mc admin info
mc mb data
mc cp ~/Downloads/mydata data/
mc ls data/
```

Follow the MinIO Client [Quickstart Guide](https://docs.min.io/community/minio-object-store/reference/minio-mc.html#quickstart) for further instructions.

## Explore Further

- [The MinIO documentation website](https://docs.min.io/community/minio-object-store/index.html)
- [MinIO Erasure Code Overview](https://docs.min.io/community/minio-object-store/operations/concepts/erasure-coding.html)
- [Use `mc` with MinIO Server](https://docs.min.io/community/minio-object-store/reference/minio-mc.html)
- [Use `minio-go` SDK with MinIO Server](https://docs.min.io/enterprise/aistor-object-store/developers/sdk/go/)

## Contribute to MinIO Project

Please follow MinIO [Contributor's Guide](https://github.com/minio/minio/blob/master/CONTRIBUTING.md) for guidance on making new contributions to the repository.

## License

- MinIO source is licensed under the [GNU AGPLv3](https://github.com/minio/minio/blob/master/LICENSE).
- MinIO [documentation](https://github.com/minio/minio/tree/master/docs) is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
- [License Compliance](https://github.com/minio/minio/blob/master/COMPLIANCE.md)


minio

Moxy is a simple mocker and proxy application server, you can create mock endpoints as well as proxy requests in case no mock exists for the endpoint

# Moxy

[![GoDoc](https://godoc.org/github.com/sinhashubham95/moxy?status.svg)](https://pkg.go.dev/github.com/sinhashubham95/moxy)
[![Release](https://img.shields.io/github/v/release/sinhashubham95/moxy?sort=semver)](https://github.com/sinhashubham95/moxy/releases)
[![Report](https://goreportcard.com/badge/github.com/sinhashubham95/moxy)](https://goreportcard.com/report/github.com/sinhashubham95/moxy)
[![Coverage Status](https://coveralls.io/repos/github/sinhashubham95/moxy/badge.svg?branch=master)](https://coveralls.io/github/sinhashubham95/moxy?branch=master)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#server-applications)

Moxy is a simple mocker and proxy application server. Here you can create mock endpoints as well as proxy requests in case no mock exists for the endpoint.

## How it works

![Moxy Architecture Diagram](./moxy.png)

## Features

### Small, Pragmatic and Easy to Use

- Dockerized

- Compiled

- Easily configurable via Environment Variables

- Self-contained, does not require Go or any other dependency, just run the binary or the container

### File-based Persistence

- No heavy database involved.

- Saves the mock endpoints in files.

### Security

- TLS can be enabled by providing your own SSL/TLS Certificates.

### Reliability

- Uses [Go Actuator](https://github.com/sinhashubham95/go-actuator)

- Fully Tested, Unit, Functional & Linted & 0 Race Conditions Detected.

### Customizations

- Mock endpoints created are highly customizable.

- Application port can be configured via the environment variable.

- Database file path can be configured via the environment variable.

## Project Versioning

Moxy uses [semantic versioning](http://semver.org/). No API changes will be introduced in the minor and patch version changes. New minor versions might add additional features to the API.

## Getting Started(standalone application)

You can download a pre-compiled package for Linux or MAC OSX [here](https://github.com/sinhashubham95/moxy/releases/latest).

You can also pull the latest docker image for Moxy from [Docker Hub](https://github.com/sinhashubham95/moxy/pkgs/container/moxy).

```shell
docker pull ghcr.io/sinhashubham95/moxy:latest
```

Create an empty directory, change into it and run the following to start Moxy:

```shell
docker run --rm --user $(id -u):$(id -g) -v $PWD:/data -p 9091:9091 sinhashubham95/moxy -host 0.0.0.0
```

The container will have access to the current local directory and all sub-folders.

## Usage

### Mock - POST /moxy/mock

This is used to create a new mock endpoint. Each mock endpoint created can be tagged, which means you can create multiple mocks for the same endpoint.

```http request
POST /moxy/mock

{
    "tag": "",
    "method": "",
    "path": "",
    "responseDelayInMillis": 0,
    "responseStatus": 0,
    "responseBody": {}
}
```

1. **Tag**: This is used to tag the created mock endpoint. It is used to set the context for this endpoint. You can have many instances of the same endpoint.

2. **Method**: This is the request method for this endpoint. It can either be `GET`, `POST`, `PUT ` or `DELETE`.

3. **Path**: This is the request path for this endpoint. Note that the request path should not start with either `/actuator` or `/moxy`.

4. **Response Delay In Millis**: This is the delay added before actually returned the mocked response. Note that this delay is over and above the delay added over the network. In other words, this is the server side delay. It can be useful in testing the resiliency of the applications using this endpoint and testing the timeout functionality.

5. **Response Status**: This is the status code for the mocked response. It should be in the range of a valid HTTP status code which is `>=100` and `<= 599`.

6. **Response Body**: This is the response body for the mocked response. If it is a JSON, it can be provided as a JSON body itself, but anything apart from JSON has to be converted to a string and sent. Don't worry the mocked response will be returned with the correct type, that will be taken care of automatically. 

### Remove Mock - DELETE /moxy/unMock

This is used to remove the existing mock endpoint.

```http request
DELETE /moxy/unMock

{
    "tag": "",
    "method": "",
    "path": ""
}
```

1. **Tag**: This is used to tag the created mock endpoint. It is used to set the context for this endpoint. You can have many instances of the same endpoint.

2. **Method**: This is the request method for this endpoint. It can either be `GET`, `POST`, `PUT ` or `DELETE`.

3. **Path**: This is the request path for this endpoint. Note that the request path should not start with either `/actuator` or `/moxy`.

### Calling any Endpoint

This is used to call any endpoint. If any mock exists for that endpoint, then the mocked response will be returned, otherwise the actual endpoint will be called.

The following 2 mandatory headers should be passed with any such request.

1. **Tag(X-Tag)**: This is the tag used while creating the mock endpoint, to query the mock for the current context.

2. **Actual Base Url(X-Url)**: This is the actual url that will be used to call the actual endpoint, or basically proxy to the actual server, in case no mock exists.

## Example(Using the following actual endpoint - https://www.google.co.in/imghp)

Create a mock endpoint as follows.

```http request
POST /moxy/mock

{
    "tag": "1234",
    "method": "GET",
    "path": "/imghp",
    "responseDelayInMillis": 200,
    "responseStatus": 200,
    "responseBody": {
        "naruto": "rocks"
    }
}
```

Create another mock endpoint with the same request method and path but a different context(tag).

```http request
POST /moxy/mock

{
    "tag": "5678",
    "method": "GET",
    "path": "/imghp",
    "responseDelayInMillis": 200,
    "responseStatus": 200,
    "responseBody": "naruto always rocks"
}
```

Try calling this endpoint with the first tag.

```http request
GET /naruto

X-Tag 1234
X-Url https://www.google.co.in
```

You will get the following response.

```json
{
  "naruto": "rocks"
}
```

Now if you call this with the second tag.

```http request
GET /naruto

X-Tag 5678
X-Url https://www.google.co.in
```

You will get the following response.

```text
naruto always rocks
```

Now try deleting the mock for the first tag.

```http request
DELETE /moxy/unMock

{
    "tag": "1234",
    "method": "GET",
    "path": "/imghp"
}
```

Now again try calling the endpoint with the first tag.

```http request
GET /naruto

X-Tag 1234
X-Url https://www.google.co.in
```

The actual endpoint will be called, and the following response you could see.

```html
<!doctype html><html itemscope="" itemtype="http://schema.org/WebPage" lang="en-IN"><head><meta content="Google Images. The most comprehensive image search on the web." name="description"><meta content="text/html; charset=UTF-8" http-equiv="Content-Type"><meta content="/images/branding/googleg/1x/googleg_standard_color_128dp.png" itemprop="image"><title>Google Images</title><script nonce="YYH7DCMo/2WXGV6FU3QJIw==">(function(){window.google={kEI:'Lh_9YKabNIOI-Abk-5CoCg',kEXPI:'0,772215,1,530320,56873,954,755,4350,206,4804,926,1390,383,246,5,1354,5251,1122515,1197765,518,328984,51224,16114,28684,17572,4859,1361,3472,5819,3023,3894,13691,4020,978,13228,3847,4192,6430,1141,7512,5875,234,4282,2778,919,5081,1593,1279,2212,239,291,149,1943,1987,210,4100,108,3406,606,2025,2295,14670,604,2623,2845,7,5599,6755,5096,7876,5037,3407,908,2,941,2614,13142,3,576,1014,1,5444,149,11323,2652,4,1528,2304,1236,5226,577,74,1983,2626,2015,4067,7434,2110,1714,3050,2658,4242,3114,31,13628,2305,639,7079,3772,3494,3269,665,2522,3287,2320,228,992,3102,20,3118,8,906,3,1324,2217,2,8994,5715,1816,281,38,874,5998,12520,2,1394,1525,8,1273,1715,2,3057,723,2,1813,2,1,3,3004,20,1214,3,33,3,5388,3,90,594,784,310,3,435,2379,2422,1274,4578,1576,3,471,578,3,1066,172,3412,2039,101,2,1040,1160,1266,3,3426,2,1712,290,2381,1575,1144,3482,1063,3,123,24,724,3857,758,1447,86,2370,12,2,1458,72,223,2130,408,2,2,5,1858,442,117,394,1996,6,54,70,899,1513,335,87,172,383,51,275,894,158,190,141,427,47,281,85,3,832,280,83,266,1387,523,1258,296,612,1290,332,558,462,123,658,233,635,1609,696,158,434,153,209,1265,103,231,8,316,5609465,99,91,36,220,58,2,69,5996740,2800696,882,444,1,2,80,1,1796,1,9,2,2551,1,748,141,795,563,1,4265,1,1,2,1331,3299,843,2609,155,17,13,72,139,4,2,20,2,169,13,19,46,5,39,96,548,29,2,2,1,2,1,2,2,7,4,1,2,2,2,2,2,2,312,41,513,186,1,1,158,3,2,2,2,2,2,4,2,3,3,236,22,6,5,10,40,2,15,23654791,299865,2867254,1171783,7,2307,277,61,3,2340,74,538,542,5,1701,772339',kBL:'k8M4'};google.sn='imghp';google.kHL='en-IN';})();(function(){
var f=this||self;var h,k=[];function l(a){for(var b;a&&(!a.getAttribute||!(b=a.getAttribute("eid")));)a=a.parentNode;return b||h}function m(a){for(var b=null;a&&(!a.getAttribute||!(b=a.getAttribute("leid")));)a=a.parentNode;return b}
function n(a,b,c,d,g){var e="";c||-1!==b.search("&ei=")||(e="&ei="+l(d),-1===b.search("&lei=")&&(d=m(d))&&(e+="&lei="+d));d="";!c&&f._cshid&&-1===b.search("&cshid=")&&"slh"!==a&&(d="&cshid="+f._cshid);c=c||"/"+(g||"gen_204")+"?atyp=i&ct="+a+"&cad="+b+e+"&zx="+Date.now()+d;/^http:/i.test(c)&&"https:"===window.location.protocol&&(google.ml&&google.ml(Error("a"),!1,{src:c,glmm:1}),c="");return c};h=google.kEI;google.getEI=l;google.getLEI=m;google.ml=function(){return null};google.log=function(a,b,c,d,g){if(c=n(a,b,c,d,g)){a=new Image;var e=k.length;k[e]=a;a.onerror=a.onload=a.onabort=function(){delete k[e]};a.src=c}};google.logUrl=n;}).call(this);(function(){
google.y={};google.sy=[];google.x=function(a,b){if(a)var c=a.id;else{do c=Math.random();while(google.y[c])}google.y[c]=[a,b];return!1};google.sx=function(a){google.sy.push(a)};google.lm=[];google.plm=function(a){google.lm.push.apply(google.lm,a)};google.lq=[];google.load=function(a,b,c){google.lq.push([[a],b,c])};google.loadAll=function(a,b){google.lq.push([a,b])};google.bx=!1;google.lx=function(){};}).call(this);google.f={};(function(){
document.documentElement.addEventListener("submit",function(b){var a;if(a=b.target){var c=a.getAttribute("data-submitfalse");a="1"==c||"q"==c&&!a.elements.q.value?!0:!1}else a=!1;a&&(b.preventDefault(),b.stopPropagation())},!0);document.documentElement.addEventListener("click",function(b){var a;a:{for(a=b.target;a&&a!=document.documentElement;a=a.parentElement)if("A"==a.tagName){a="1"==a.getAttribute("data-nohref");break a}a=!1}a&&b.preventDefault()},!0);}).call(this);</script><style>#gbar,#guser{font-size:13px;padding-top:1px !important;}#gbar{height:22px}#guser{padding-bottom:7px !important;text-align:right}.gbh,.gbd{border-top:1px solid #c9d7f1;font-size:1px}.gbh{height:0;position:absolute;top:24px;width:100%}@media all{.gb1{height:22px;margin-right:.5em;vertical-align:top}#gbar{float:left}}a.gb1,a.gb4{text-decoration:underline !important}a.gb1,a.gb4{color:#00c !important}.gbi .gb4{color:#dd8e27 !important}.gbf .gb4{color:#900 !important}
</style><style>body,td,a,p,.h{font-family:arial,sans-serif}body{margin:0;overflow-y:scroll}#gog{padding:3px 8px 0}td{line-height:.8em}.gac_m td{line-height:17px}form{margin-bottom:20px}.h{color:#1558d6}em{font-weight:bold;font-style:normal}.lst{height:25px;width:496px}.gsfi,.lst{font:18px arial,sans-serif}.gsfs{font:17px arial,sans-serif}.ds{display:inline-box;display:inline-block;margin:3px 0 4px;margin-left:4px}input{font-family:inherit}body{background:#fff;color:#000}a{color:#4b11a8;text-decoration:none}a:hover,a:active{text-decoration:underline}.fl a{color:#1558d6}a:visited{color:#4b11a8}.sblc{padding-top:5px}.sblc a{display:block;margin:2px 0;margin-left:13px;font-size:11px}.lsbb{background:#f8f9fa;border:solid 1px;border-color:#dadce0 #70757a #70757a #dadce0;height:30px}.lsbb{display:block}#WqQANb a{display:inline-block;margin:0 12px}.lsb{background:url(/images/nav_logo229.png) 0 -261px repeat-x;border:none;color:#000;cursor:pointer;height:30px;margin:0;outline:0;font:15px arial,sans-serif;vertical-align:top}.lsb:active{background:#dadce0}.lst:focus{outline:none}.prms{color:#c5221f;font-size:13px}.sshppd{font-size:13px;margin:32px 0 26px}.sshpplo span{color:#c5221f}.sshpplt{margin:15px 0 30px}</style><script nonce="YYH7DCMo/2WXGV6FU3QJIw=="></script></head><body bgcolor="#fff"><script nonce="YYH7DCMo/2WXGV6FU3QJIw==">(function(){var src='/images/nav_logo229.png';var iesg=false;document.body.onload = function(){window.n && window.n();if (document.images){new Image().src=src;}
if (!iesg){document.f&&document.f.q.focus();document.gbqf&&document.gbqf.q.focus();}
}
})();</script><div id="mngb"><div id=gbar><nobr><a class=gb1 href="https://www.google.co.in/webhp?tab=iw">Search</a><b class=gb1>Images</b><a class=gb1 href="https://maps.google.co.in/maps?hl=en&tab=il">Maps</a><a class=gb1 href="https://play.google.com/?hl=en&tab=i8">Play</a><a class=gb1 href="https://www.youtube.com/?gl=IN&tab=i1">YouTube</a><a class=gb1 href="https://news.google.com/?tab=in">News</a><a class=gb1 href="https://mail.google.com/mail/?tab=im">Gmail</a><a class=gb1 href="https://drive.google.com/?tab=io">Drive</a><a class=gb1 style="text-decoration:none" href="https://www.google.co.in/intl/en/about/products?tab=ih"><u>More</u> &raquo;</a></nobr></div><div id=guser width=100%><nobr><span id=gbn class=gbi></span><span id=gbf class=gbf></span><span id=gbe></span><a href="http://www.google.co.in/history/optout?hl=en" class=gb4>Web History</a> |<a  href="/preferences?hl=en" class=gb4>Settings</a> |<a target=_top id=gb_70 href="https://accounts.google.com/ServiceLogin?hl=en&passive=true&continue=https://www.google.co.in/imghp&ec=GAZAAg" class=gb4>Sign in</a></nobr></div><div class=gbh style=left:0></div><div class=gbh style=right:0></div></div><center><br clear="all" id="lgpd"><div id="lga"><div style="padding:28px 0 3px"><div style="height:110px;width:276px;background:url(/intl/en_ALL/images/branding/googlelogo/1x/googlelogo_white_background_color_272x92dp.png) no-repeat" title="Google Images" align="left" id="hplogo"><div style="font-size:16px;font-weight:bold;position:relative;top:70px;color:#1a73e8;right:115px;float:right" nowrap=""><span>images</span></div></div></div><br></div><form action="https://www.google.co.in/search" name="f"><table cellpadding="0" cellspacing="0"><tr valign="top"><td width="25%">&nbsp;</td><td align="center" nowrap=""><input name="tbm" value="isch" type="hidden"><input name="ie" value="ISO-8859-1" type="hidden"><input value="en-IN" name="hl" type="hidden"><input name="source" type="hidden" value="hp"><input name="biw" type="hidden"><input name="bih" type="hidden"><div class="ds" style="height:32px;margin:4px 0"><input class="lst" style="margin:0;padding:5px 8px 0 6px;vertical-align:top;color:#000" autocomplete="off" value="" title="Search Images" maxlength="2048" name="q" size="57"></div><span class="ds"><span class="lsbb"><input class="lsb" value="Search Images" name="btnG" type="submit"></span></span></td><td class="fl sblc" align="left" valign="middle" nowrap="" width="25%"><a href="/advanced_image_search?hl=en-IN&amp;authuser=0">Advanced&nbsp;Image&nbsp;Search</a></td></tr></table><input id="gbv" name="gbv" type="hidden" value="1"><script nonce="YYH7DCMo/2WXGV6FU3QJIw==">(function(){
var a,b="1";if(document&&document.getElementById)if("undefined"!=typeof XMLHttpRequest)b="2";else if("undefined"!=typeof ActiveXObject){var c,d,e=["MSXML2.XMLHTTP.6.0","MSXML2.XMLHTTP.3.0","MSXML2.XMLHTTP","Microsoft.XMLHTTP"];for(c=0;d=e[c++];)try{new ActiveXObject(d),b="2"}catch(h){}}a=b;if("2"==a&&-1==location.search.indexOf("&gbv=2")){var f=google.gbvu,g=document.getElementById("gbv");g&&(g.value=a);f&&window.setTimeout(function(){location.href=f},0)};}).call(this);</script></form><div id="gac_scont"></div><div style="font-size:83%;min-height:3.5em"><br></div><span id="footer"><div style="font-size:10pt"><div style="margin:19px auto;text-align:center" id="WqQANb"><a href="/intl/en/ads/">Advertising Programs</a><a href="http://www.google.co.in/services/">Business Solutions</a><a href="/intl/en/about.html">About Google</a></div></div><p style="font-size:8pt;color:#70757a">&copy; 2021 - <a href="/intl/en/policies/privacy/">Privacy</a> -<a href="/intl/en/policies/terms/">Terms</a></p></span></center><script nonce="YYH7DCMo/2WXGV6FU3QJIw==">(function(){window.google.cdo={height:757,width:1440};(function(){
var a=window.innerWidth,b=window.innerHeight;if(!a||!b){var c=window.document,d="CSS1Compat"==c.compatMode?c.documentElement:c.body;a=d.clientWidth;b=d.clientHeight}a&&b&&(a!=google.cdo.width||b!=google.cdo.height)&&google.log("","","/client_204?&atyp=i&biw="+a+"&bih="+b+"&ei="+google.kEI);}).call(this);})();</script><script nonce="YYH7DCMo/2WXGV6FU3QJIw==">(function(){google.xjs={ck:'',cs:'',excm:[],pml:false};})();</script><script nonce="YYH7DCMo/2WXGV6FU3QJIw==">(function(){var u='/xjs/_/js/k\x3dxjs.hp.en.9gLGBHDOM4E.O/m\x3dsb_he,d/am\x3dAPgEWA/d\x3d1/ed\x3d1/rs\x3dACT90oEXm9MrN4B8xXQY6N86St4ZoOKYHQ';
var e=this||self,f=function(a){return a};var g;var l=function(a,b){this.g=b===h?a:""};l.prototype.toString=function(){return this.g+""};var h={};function m(){var a=u;google.lx=function(){n(a);google.lx=function(){}};google.bx||google.lx()}
function n(a){google.timers&&google.timers.load&&google.tick&&google.tick("load","xjsls");var b=document;var c="SCRIPT";"application/xhtml+xml"===b.contentType&&(c=c.toLowerCase());c=b.createElement(c);if(void 0===g){b=null;var k=e.trustedTypes;if(k&&k.createPolicy){try{b=k.createPolicy("goog#html",{createHTML:f,createScript:f,createScriptURL:f})}catch(p){e.console&&e.console.error(p.message)}g=b}else g=b}a=(b=g)?b.createScriptURL(a):a;a=new l(a,h);c.src=a instanceof l&&a.constructor===l?a.g:"type_error:TrustedResourceUrl";var d;a=(c.ownerDocument&&c.ownerDocument.defaultView||window).document;(d=(a=null===(d=a.querySelector)||void 0===d?void 0:d.call(a,"script[nonce]"))?a.nonce||a.getAttribute("nonce")||"":"")&&c.setAttribute("nonce",d);document.body.appendChild(c);google.psa=!0};setTimeout(function(){m()},0);})();(function(){window.google.xjsu='/xjs/_/js/k\x3dxjs.hp.en.9gLGBHDOM4E.O/m\x3dsb_he,d/am\x3dAPgEWA/d\x3d1/ed\x3d1/rs\x3dACT90oEXm9MrN4B8xXQY6N86St4ZoOKYHQ';})();function _DumpException(e){throw e;}
function _F_installCss(c){}
(function(){google.jl={attn:false,blt:'none',chnk:0,dw:false,emtn:0,end:0,ine:false,lls:'default',pdt:0,rep:0,sif:false,snet:true,strt:0,ubm:false,uwp:true};})();(function(){var pmc='{\x22d\x22:{},\x22sb_he\x22:{\x22agen\x22:true,\x22cgen\x22:true,\x22client\x22:\x22img\x22,\x22dh\x22:true,\x22dhqt\x22:true,\x22ds\x22:\x22i\x22,\x22ffql\x22:\x22en\x22,\x22host\x22:\x22google.co.in\x22,\x22isbh\x22:28,\x22jsonp\x22:true,\x22msgs\x22:{\x22cibl\x22:\x22Clear Search\x22,\x22dym\x22:\x22Did you mean:\x22,\x22lcky\x22:\x22I\\u0026#39;m Feeling Lucky\x22,\x22lml\x22:\x22Learn more\x22,\x22oskt\x22:\x22Input tools\x22,\x22psrc\x22:\x22This search was removed from your \\u003Ca href\x3d\\\x22/history\\\x22\\u003EWeb History\\u003C/a\\u003E\x22,\x22psrl\x22:\x22Remove\x22,\x22sbit\x22:\x22Search by image\x22,\x22srch\x22:\x22Google Search\x22},\x22ovr\x22:{},\x22pq\x22:\x22\x22,\x22sbas\x22:\x220 3px 8px 0 rgba(0,0,0,0.2),0 0 0 1px rgba(0,0,0,0.08)\x22,\x22sbpl\x22:16,\x22sbpr\x22:16,\x22scd\x22:10,\x22stok\x22:\x22qb6u1LJ3VhKtpclmepiiAm7jA9E\x22,\x22uhde\x22:false}}';google.pmc=JSON.parse(pmc);})();</script></body></html>
```




Moxy

Open-source alternative to Google Cloud Run and AWS App Runner. Easily deploy internal tools across a team

<p align="center">
  <img src="https://openrun.dev/openrun.png" alt="OpenRun-logo" width="300" height="250"/>

  <p align="center">App deployment simplified. Open source alternative to Google Cloud Run and AWS App Runner. Easily deploy internal tools, on a single node with Docker/Podman or onto a Kubernetes cluster.</p>
</p>

<p>
  <a href="https://github.com/openrundev/openrun/blob/main/LICENSE"><img src="https://img.shields.io/github/license/openrundev/openrun" alt="License"></a>
  <a href="https://github.com/openrundev/openrun/releases"><img src="https://img.shields.io/github/release/openrundev/openrun.svg?color=00C200" alt="Latest Release"></a>
  <a href="https://github.com/openrundev/openrun/actions"><img src="https://github.com/openrundev/openrun/workflows/CI/badge.svg" alt="Build Status"></a>
  <a href="https://app.codecov.io/github/openrundev/openrun"><img src="https://img.shields.io/codecov/c/github/openrundev/openrun" alt="Code Coverage"></a>
  <a href="https://goreportcard.com/report/github.com/openrundev/openrun"><img src="https://goreportcard.com/badge/github.com/openrundev/openrun" alt="Go Report Card"></a>
  <a href="https://landscape.cncf.io/?item=app-definition-and-development--application-definition-image-build--openrun"><img src="https://img.shields.io/badge/CNCF-0086FF" alt="Listed in CNCF landscape"></a>
  <a href="https://www.bestpractices.dev/projects/11301"><img src="https://www.bestpractices.dev/projects/11301/badge"></a>
  
  <img src="https://img.shields.io/github/downloads/openrundev/openrun/total.svg" alt="downloads"/>
</p>

### Menu

- [Overview](#overview)
- [FAQ](#faq)
- [Features](#features)
- [Roadmap](#roadmap)
- [Setup](#setup)
- [Documentation](#documentation)
- [Getting help](#getting-help)
- [Contributing](#contributing)

## Overview

OpenRun is an Apache-2.0 licensed open source web app deployment platform, with a focus on deploying internal tools. OpenRun makes it easy to **declaratively** deploy containerized web apps. OpenRun can deploy apps on a single-node or onto a Kubernetes cluster. OpenRun provides declarative GitOps based blue-green deployment, OAuth/OIDC/SAML access controls, TLS certs & secrets management. OpenRun is built for teams to easily deploy internal tools, with full RBAC support. OpenRun apps are deployed directly from the git repo, no build server required. OpenRun scales idles apps down to zero and supports atomic updates across multiple apps.

Some of the unique features of OpenRun are:

- Create and manage apps declaratively, through GitOps
- Easily upgrade from single-node to Kubernetes, with no config changes required
- Domain based or path based routing, with auto-TLS
- OAuth/OpenID/SAML/Cert based auth
- RBAC for admin operation and for app access
- Scales idle apps down to zero
- Staged deployment, for code and config changes
- Atomic (all or nothing) updates across apps

This repo hosts the source code for OpenRun. The source for the documentation site [openrun.dev](https://openrun.dev) is in the docs folder. App specifications, which are templates to create apps, are defined in the [appspecs](https://github.com/openrundev/appspecs) repo. Sample apps are in the [apps](https://github.com/openrundev/apps) repo.

<img alt="OpenRun intro gif" src="https://openrun.dev/intro_dark_small.gif"/>

## FAQ

<details open>
  <summary><b>How does OpenRun compare to other deployment solutions like Coolify/Dokku/CapRover etc?</b></summary>

> The main differences are:
>
> - OpenRun is declarative. After initial OpenRun setup. Instead of using CLI commands or UI operations, all operations including creating new app and updating config for existing apps can be doing by updating a config file in Git. With most other solution, app creation/update is done manually through CLI or UI. Only app source code update can be done through Git.
> - OpenRun can deploy apps on a single machine with Docker/Podman or it can deploy apps onto a Kubernetes cluster. Most other solutions do not support deployment to Kubernetes.
> - OpenRun is implemented as a web server, it does not depend on external web server like Nginx/Traefik. This simplifies end-user usage and allows OpenRun to implement features like scale down to zero (for app containers) and OAuth/SAML/Cert based auth with RBAC.
> - OpenRun supports features like staged deployment and automatic dev env setup which are not available in other solutions.

</details>

<details>
  <summary><b>Why is declarative configuration useful?</b></summary>

> Imperative CLI or UI operation are easy to start with, but they make it difficult to track changes and rollback updates. With a declarative config, all changes are version controlled. It is easy to create a new environment, since everything is in Git. If multiple folks are making config changes in a team, declarative systems are easier to manage.
>
> Declarative configuration is what makes Kubernetes and Terraform useful. OpenRun brings declarative configuration to web app deployment. Instead of writing pages of YAML, each app is specified as a couple of lines of Starlark (python-like) config. For example, see [utils.star](https://github.com/openrundev/openrun/blob/main/examples/utils.star).

</details>

<details>
  <summary><b>What types of apps can be deployed with OpenRun?</b></summary>

> OpenRun can deploy any web app which runs in a single container. OpenRun supports [AppSpecs](https://openrun.dev/docs/container/overview/#app-specs) which allow zero-config deployment of frameworks like Streamlit/Gradio/FastHTML/NiceGUI/Shiny/Reflex based apps. For frameworks which have a AppSpec, no Dockerfile is required, no code changes are required in the app source code. For frameworks which do not have an AppSpec defined, a Dockerfile needs to be present in the app source repo.
>
> OpenRun does NOT support apps which require multiple containers using Docker Compose. The target use case is internal tools talking to existing API endpoints and web apps where the database is externally managed.

</details>

<details>
  <summary><b>Does OpenRun support deployment of internal tools by teams?</b></summary>

> Yes, deployment of internal tools by teams is a target [use case](https://openrun.dev/docs/use-cases/team/). Features which are built for this use case include:
>
> - **Declarative Config**: Manage apps by [declaratively](https://openrun.dev/docs/applications/overview/#declarative-app-management) in git, allowing team to do follow regular SDLC for config
> - **OAuth/OIDC/SAML with RBAC**: Manage who can access which app using [RBAC](https://openrun.dev/docs/configuration/rbac/)
> - **Audit Logs**: All operations and API calls are automatically logged in [audit trail](https://openrun.dev/docs/applications/audit/)

</details>

<details>
  <summary><b>How is OpenRun deployed?</b></summary>

> OpenRun can be deployed on a single node easily (Linux, Windows or OSX), using a SQLite database for storing metadata. Docker/Podman is the only dependency. OpenRun can be deployed across multiple machines, using an external Postgres database for storing metadata.
>
> OpenRun can also be deployed on Kubernetes using a Helm chart. On Kubernetes, OpenRun will avoid the need to setup a build system like Jenkins, CD with ArgoCD and an IDP like BackStage. Apps deployed using OpenRun are deployed as Kubernetes services, with OpenRun running as the api server/request router.

</details>

## Architecture Overview

### Single-Node Architecture

```mermaid
architecture-beta
    service client(internet)[Client]

    group host(server)[Node]
    service openrun(server)[OpenRun Server] in host
    service sqlite(database)[SQLite Metadata] in host

    group cm(server)[Docker or Podman] in host
    junction split in cm
    service app1(server)[App1] in cm
    service app2(server)[App2] in cm

    client:R --> L:openrun
    openrun:B --> T:sqlite
    openrun:R -- L:split
    split:T --> B:app1
    split:B --> T:app2
```

### Kubernetes Architecture

```mermaid
architecture-beta
    service client(internet)[Client]
    service postgres(database)[Postgres Metadata]
    service registry(server)[Container Registry]

    group k8s(server)[Kubernetes]
    service openrun(server)[OpenRun] in k8s

    group apps(server)[Deployed Apps] in k8s
    junction split in apps
    service app1(server)[App1] in apps
    service app2(server)[App2] in apps

    client:R --> L:openrun
    postgres:R <-- T:openrun
    registry:R <-- B:openrun

    openrun:R -- L:split
    split:T --> B:app1
    split:B --> T:app2
```

## Features

OpenRun can be used to:

- Deploy [containerized applications](https://openrun.dev/docs/container/overview/), OpenRun will build and manage the container lifecycle
- Automatically generate a form based UI for backend [actions](https://openrun.dev/docs/actions/)
- Add OAuth/OIDC/SAML based [auth](https://openrun.dev/docs/configuration/authentication/) and [RBAC](https://openrun.dev/docs/configuration/rbac/) for app access

OpenRun supports the following for all apps:

- [Declarative](https://openrun.dev/docs/applications/overview/#declarative-app-management) app deployment
- Atomic updates (all or none) across [multiple apps](https://openrun.dev/docs/applications/overview/#glob-pattern)
- [Staging mode](https://openrun.dev/docs/applications/lifecycle/#staging-apps) for app updates, to verify whether code and config changes work on prod before making them live.
- [Preview app](https://openrun.dev/docs/applications/lifecycle/#preview-apps) creation support, for trying out code changes.
- Support for [github integration](https://openrun.dev/docs/configuration/security/#private-repository-access), apps being directly deployed from github code.
- [Automatic SSL](https://openrun.dev/docs/configuration/networking/#enable-automatic-signed-certificate) certificate creation based on [certmagic](https://github.com/caddyserver/certmagic).
- OAuth/OIDC/SAML based [authentication](https://openrun.dev/docs/configuration/authentication/#oauth-authentication)
- Support for domain based and path based [routing](https://openrun.dev/docs/applications/routing/#request-routing) at the app level.
- Integration with [secrets managers](https://openrun.dev/docs/configuration/secrets/), to securely access secrets.

For containerized apps, OpenRun supports:

- Managing [image builds](https://openrun.dev/docs/quickstart/#containerized-applications), in dev and prod mode
- Passing [parameters](https://openrun.dev/docs/develop/#app-parameters) for the container
- Building apps from [spec](https://openrun.dev/docs/develop/#building-apps-from-spec), no code changes required in repo for [supported frameworks](https://github.com/openrundev/appspecs) (Flask, Streamlit and repos having a Dockerfile)
- Support for [pausing](https://openrun.dev/docs/container/config/) app containers which are idle

For building Hypermedia based apps, OpenRun supports:

- Automatic [error handling support](https://openrun.dev/docs/plugins/overview/#automatic-error-handling)
- Automatic creation of ECMAScript modules using [esbuild](https://esbuild.github.io/) for dependencies.
- Support for [TailwindCSS](https://tailwindcss.com/) and [DaisyUI](https://daisyui.com/) watcher integration.
- Backend app code runs in a [security sandbox](https://openrun.dev/docs/applications/appsecurity/#security-model), with allowlist based permissions.
- [No build step](https://openrun.dev/docs/develop/#app-lifecycle), the development artifacts are ready for production use.
- Support for application data persistence using SQLite
- Virtual filesystem with [content hash based file names](https://openrun.dev/docs/develop/templates/#static-function) backed by SQLite database, enabling aggressive static content caching.
- Brotli compression for static artifacts, HTTP early hints support for performance.

## Roadmap

The feature roadmap for OpenRun is:

- Adding more app specs, to support additional frameworks out of the box.
- Support for app scaling on Kubernetes based on concurrent APIs. Scaling based on CPU/memory metrics is supported right now.
- Support for server level plugin permissions allowlist. Currently, every plugin call has to be explicitly approved at the app level.
- Support for using same container image for stage and prod app, when possible.
- Support for verified promote mode, where health checks are done on stage app before promote is done.

## Setup

### Certs and Default password

OpenRun manages TLS cert using LetsEncrypt for prod environments. For dev environment, OpenRun uses [mkcert](https://github.com/FiloSottile/mkcert) for local certs. Installing OpenRun using brew will automatically install mkcert.

For container based apps, Docker or Podman or Orbstack should be installed and running on the machine. OpenRun automatically detects the container manager to use.

### Install OpenRun On OSX/Linux

To install on OSX/Linux, run

```shell
curl -sSL https://openrun.dev/install.sh | sh
```

Start a new terminal (to get the updated env) and run `openrun server start` to start the OpenRun service.

### Brew Install

To install using brew, run

```
brew tap openrundev/homebrew-openrun
brew install openrun
brew services start openrun
```

### Install On Windows

To install on Windows, run

```
powershell -Command "iwr https://openrun.dev/install.ps1 -useb | iex"
```

Start a new command window (to get the updated env) and run `openrun server start` to start the OpenRun service.

### Kubernetes Install

See [kubernetes docs](https://openrun.dev/docs/container/kubernetes/) for details on installing on Kubernetes using Helm chart and Terraform based infra setup.

### Install Apps

Once OpenRun server is running, to install apps declaratively, open a new window and run

```
openrun apply --approve github.com/openrundev/openrun/examples/utils.star
```

To schedule a background sync, which automatically applies the latest app config, run

```
openrun sync schedule --approve --promote github.com/openrundev/openrun/examples/utils.star
```

To install apps using the CLI (imperative mode), run

```
openrun app create --approve github.com/openrundev/apps/system/list_files /files
openrun app create --approve github.com/openrundev/apps/system/disk_usage /disk_usage
openrun app create --approve github.com/openrundev/apps/utils/bookmarks /book
```

Open https://localhost:25223 to see the app listing. The disk usage app is available at https://localhost:25223/disk_usage (port 25222 for HTTP). The bookmark manager is available at https://localhost:25223/book, the list files app is available at https://localhost:25223/files.

See [installation]({{< ref "installation" >}}) for details. See [config options]({{< ref "configuration" >}}) for configuration options. To enable Let's Encrypt certificates, see [Automatic SSL]({{< ref "configuration/networking/#enable-automatic-signed-certificate" >}}).

The release binaries are also available at [releases](https://github.com/openrundev/openrun/releases). See [install from source]({{< ref "installation/#install-from-source" >}}) to build from source.

To install a containerized app, ensure either Docker or Podman is running and run

```
openrun app create --spec python-streamlit --branch master --approve github.com/streamlit/streamlit-example /streamlit
```

If the source repo has a `Dockerfile` or `Containerfile`, run

```
openrun app create --spec container --approve <source_path> /myapp
```

to install the app.

### Build from source

To install a release build, follow steps in the [installation docs](https://openrun.dev/docs/installation/#install-release-build).

To install from source:

- Ensure that a recent version of [Go](https://go.dev/doc/install) is available, version 1.21.0 or newer
- Checkout the OpenRun repo, cd to the checked out folder
- Build the openrun binary and place in desired location, like $HOME

```shell
# Ensure go is in the $PATH
mkdir $HOME/openrun_source && cd $HOME/openrun_source
git clone -b main https://github.com/openrundev/openrun && cd openrun
export OPENRUN_HOME=$HOME/clhome && mkdir -p $OPENRUN_HOME/config
go build -o $OPENRUN_HOME/openrun ./cmd/openrun/
```

### Initial Configuration For Source Install

To use the openrun service, you need an initial config file with the service password and a work directory. The below instructions assume you are using $HOME/clhome/openrun.toml as the config file and $HOME/clhome as the work directory location.

- Create the clhome directory
- Create the openrun.toml file, and create a randomly generate password for the **admin** user account

```shell
cd $OPENRUN_HOME
git clone -C config https://github.com/openrundev/appspecs
$OPENRUN_HOME/openrun password > $OPENRUN_HOME/openrun.toml
$OPENRUN_HOME/openrun server start
```

The service will be started on [https://localhost:25223](https://127.0.0.1:25223) by default (HTTP port 25222).

## Documentation

OpenRun docs are at https://openrun.dev/docs/. For doc bugs, raise a GitHub issue in the [docs](https://github.com/openrundev/docs) repo.

## Getting help

Please use [Github Discussions](https://github.com/openrundev/openrun/discussions) for discussing OpenRun related topics. Please use the bug tracker for bug reports and feature requests. The [OpenRun Discord](https://discord.gg/t2P8pJFsd7) community is another option.

## Contributing

PRs welcome for bug fixes and enhancements. For application behavior related fixes, refer the [app unit test cases](https://github.com/openrundev/openrun/tree/main/internal/app/tests). Those test run as part of regular unit tests `go test ./...`. For API related changes, OpenRun uses the [commander-cli](https://github.com/commander-cli/commander) library for [automated CLI tests](https://github.com/openrundev/openrun/tree/main/tests). To run the CLI test, run `gmake test` from the openrun home directory.

OpenRun

Stream database events from PostgreSQL to Kafka

# PSQL-Streamer

[![Go Report Card](https://goreportcard.com/badge/github.com/blind-oracle/psql-streamer)](https://goreportcard.com/report/github.com/blind-oracle/psql-streamer)
[![Coverage Status](https://coveralls.io/repos/github/blind-oracle/psql-streamer/badge.svg?branch=master)](https://coveralls.io/github/blind-oracle/psql-streamer?branch=master)
[![Build Status](https://travis-ci.org/blind-oracle/psql-streamer.svg?branch=master)](https://travis-ci.org/blind-oracle/psql-streamer)

This service receives the database events from PostgreSQL using logical replication protocol and feeds them to sinks based on the configuration file settings.
Also can receive the events from Kafka generated by e.g. another _psql-streamer_ instance.

## Event example

```json
{
  "Host": "db1",
  "Database": "test",
  "Table": "test",
  "Action": "insert",
  "WALPosition": 418152976,
  "Timestamp": "2018-07-03T16:04:27.263625156+02:00",
  "Columns": {
    "a": 369223,
    "b": "a"
  }
}
```

## Features

- You can configure a sink to receive events from several different sources (e.g. several Kafka clusters, PostgreSQL databases)
- Basic HTTP API
- Custom sources/sinks can be easily added - they only need to implement a simple interface
- **Requires PostgreSQL 10+** (although initial implementation of logical replication came in 9.4 it lacks certain features to be useful)

## Sources

### PostgreSQL

Receive database events from PostgreSQL using logical replication protocol and transform them into a common event format.

#### Features

- **WAL log position persistence**: the service persists each log position update it receives in a BoltDB database.

- **Configurable WAL logs retention** on the PostgreSQL side. To allow us to rewind back (in case we need to replay some events) the service implements delayed confirmation of applied logs. This makes PostgreSQL retain the logs for the specified replication slot for some time. See _walRetain_ parameter in the configuration file.

#### PostgreSQL configuration

- In `postgresql.conf` you need to set `wal_level = logical` to make logical replication possible. You also may need to adjust `max_wal_senders` and `max_replication_slots` to match your requirements.
- Create a publication in PostgreSQL like this: `CREATE PUBLICATION pub1 FOR ALL TABLES`. This will include in the publication all existing tables and also the ones that will be created in future. If you want only a subset of tables to be replicated - list them specifically. See [PostgreSQL documentation](https://www.postgresql.org/docs/10/static/sql-createpublication.html) for details.
- Specify the publication name in the _psql-streamer.conf_

### Kafka

Receive events which were generated by e.g. another **psql-streamer** instance from one or more Kafka topics. Expects messages in a JSON format conforming to a predefined structure (see _Event structure_ below).

#### Features

Kafka source works in batching mode with confirmation: if all events in a batch from Kafka are ACKed by sinks then we commit the whole batch or don't commit anything. The batch elements are sent concurrently using goroutines, so it should not be made very large. If several topics are specified then they're worked on in separate goroutines which should provide more parallelism.

## Sinks

### Kafka

Send events into a Kafka topic based on several configurable rules like:

- Table -> Topic mapping
- Fallback topic messages with no mapping defined

#### Kafka sink handlers

Incoming events are processed by one or more handlers that generate Kafka messages. They can be used to enrich Events with additional data or encode them in different format.

Currently there's only one handler:

- **passthrough**: simply marshal an event into JSON and send it to Kafka

### Stub

Stub sink is a discard/noop sink that can be used for testing.

## HTTP API

All requests are GET.

- **/health** is a no-op that just returns 200
- **/status** checks all sinks/sources statuses and outputs them. If something is not OK then it returns 500 instead of 200. Useful for monitoring.
- **/stats** returns statistics from all sinks/sources
- **/debug/[on|off]** toggles debugging mode for all sinks/sources
- **/metrics** gives out Prometheus metrics

## Configuration

See [psql-streamer.toml](https://github.com/blind-oracle/psql-streamer/blob/master/psql-streamer.toml) for detailed instructions.

## Download

Get RPM or DEB packages from [Releases](https://github.com/blind-oracle/psql-streamer/releases) page

## Build

**psql-streamer** is written in [Go](https://golang.org), so you need to install it first.

Then you can run `make build` to build a binary.

If you want to build RPM/DEB packages then you need to install [FPM](https://github.com/jordansissel/fpm) and then run `make rpm` or `make deb`


psql-streamer

Relay to load-balance Riemann events and/or convert them to Carbon

[![Go Report Card](https://goreportcard.com/badge/github.com/blind-oracle/riemann-relay)](https://goreportcard.com/report/github.com/blind-oracle/riemann-relay)
[![Coverage Status](https://coveralls.io/repos/github/blind-oracle/riemann-relay/badge.svg?branch=master)](https://coveralls.io/github/blind-oracle/riemann-relay?branch=master)
[![Build Status](https://travis-ci.org/blind-oracle/riemann-relay.svg?branch=master)](https://travis-ci.org/blind-oracle/riemann-relay)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go)

# riemann-relay
This is a service that receives a Riemann Protobuf-formatted event stream and sends it to one or more targets in Riemann or Graphite format.
Although that can be done in Riemann itself, this service is simpler, probably faster and lightweight (no Java)

## Features
* Receive event batches in Riemann Protobuf format (see *riemann.proto*)
* Receive events in Riemann JSON format using Websocket API
* Convert Riemann events to Carbon metrics using flexible field mapping syntax
* Send events in configurable batch sizes to any number of Riemann/Carbon targets
* Supports TCP and Unix Sockets
* Different target selection algorithms:
  - Round-Robin
  - Hash
  - Failover
  - Broadcast
* Optional failover to other targets if the selected one is down (in Hash and Round-Robin modes)
* Prometheus metrics
* Log stats periodically
* Configurable batch and buffer sizes, flush intervals, timeouts
* Build RPM and DEB packages

See *riemann-relay.conf* for more details on features and how to configure them

## Performance
On 2 average CPU cores it's able to handle about 500k events per second, depending on batch size and incoming Riemann message sizes.
It will scale to more CPUs when using more targets and clients (each target and client gets it's own thread).
There's a room for optimizations, though.

## JSON URI and Event structure for Websocket
URI: ws://1.1.1.1:1234/events

```json
{
    "host": "host1",
    "service": "svc1",
    "description": "cool",
    "state": "ok",
    "tags": ["tag1", "tag2"],
    "metric": 123,
    "time": "2018-04-10T13:36:04.787Z",
    "attributes": [
        {
            "key": "key1",
            "value": "val1"
        }
    ]
}
```

## Install
For now in the releases only binaries for *linux-amd64* are available. For other platforms see the *Build* section below.

## Build
**riemann-relay** is written in [Go](https://golang.org/) and uses [dep](https://github.com/golang/dep) as a dependency manager, so you need to install them first.

Then:
```bash
# dep ensure
# go build
```

## Packaging
To build RPM & DEB packages you'll need [gox](https://github.com/mitchellh/gox) and [fpm](https://github.com/jordansissel/fpm).

Then just do one of:
```bash
# make rpm
# make deb
```

## Run
```bash
# /path/to/riemann-relay -config /etc/riemann-relay.conf
```

The logging currently goes to stdout.
Use *-debug* option to get a lot more detailed output (not for production).


riemann-relay

High-performance PHP application server, load-balancer and process manager

<a href="https://roadrunner.dev" target="_blank">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://github.com/roadrunner-server/.github/assets/8040338/e6bde856-4ec6-4a52-bd5b-bfe78736c1ff">
    <img align="center" src="https://github.com/roadrunner-server/.github/assets/8040338/040fb694-1dd3-4865-9d29-8e0748c2c8b8">
  </picture>
</a>
<p align="center">
 <a href="https://packagist.org/packages/spiral/roadrunner"><img src="https://poser.pugx.org/spiral/roadrunner/version"></a>
	<a href="https://pkg.go.dev/github.com/roadrunner-server/roadrunner/v2025?tab=doc"><img src="https://godoc.org/github.com/roadrunner-server/roadrunner/v2025?status.svg"></a>
    <a href="https://twitter.com/spiralphp"><img src="https://img.shields.io/twitter/follow/spiralphp?style=social"></a>
    <a href="https://codecov.io/gh/roadrunner-server/roadrunner/"><img src="https://codecov.io/gh/roadrunner-server/roadrunner/branch/master/graph/badge.svg"></a>
	<a href="https://github.com/roadrunner-server/roadrunner/actions"><img src="https://github.com/roadrunner-server/roadrunner/workflows/rr_cli_tests/badge.svg" alt=""></a>
	<a href="https://goreportcard.com/report/github.com/roadrunner-server/roadrunner/v2"><img src="https://goreportcard.com/badge/github.com/roadrunner-server/roadrunner/v2"></a>
	<a href="https://discord.gg/TFeEmCs"><img src="https://img.shields.io/badge/discord-chat-magenta.svg"></a>
	<a href="https://packagist.org/packages/spiral/roadrunner"><img src="https://img.shields.io/packagist/dd/spiral/roadrunner?style=flat-square"></a>
    <img alt="All releases" src="https://img.shields.io/github/downloads/roadrunner-server/roadrunner/total">
  <a href="https://gurubase.io/g/roadrunner"><img src="https://img.shields.io/badge/Gurubase-Ask%20RoadRunner%20Guru-006BFF?style=flat-square"></a>
</p>

RoadRunner is an open-source (MIT licensed) high-performance PHP application server, process manager written in Go and powered with plugins ❤️.
It supports running as a service with the ability to extend its functionality on a per-project basis with plugins.


# Features

**RoadRunner** features a range of plugins, including `HTTP(S)/2/3` and `fCGI` servers that are compatible with PSR-7/PSR-17 standards. This is just one of its many capabilities. It serves as an effective alternative to the traditional Nginx+FPM setup, providing improved performance and more flexibility. Its extensive plugin options go far beyond just `HTTP(S)/2/3` and `fCGI` servers, offering a broad range of functionalities:
- Queue drivers: RabbitMQ, Kafka, SQS, Beanstalk, NATS, In-Memory.
- KV drivers: Redis, Memcached, BoltDB, In-Memory.
- OpenTelemetry protocol support (`gRPC`, `http`, `jaeger`).
- [Workflow engine](https://github.com/temporalio/sdk-php) via [Temporal](https://temporal.io).
- `gRPC` server. For increased speed, the `protobuf` extension can be used.
- `HTTP(S)/2/3` and `fCGI` servers features **automatic TLS management**, **103 Early Hints** support and middleware like: Static, Headers, gzip, prometheus (metrics), send (x-sendfile), OTEL, proxy_ip_parser, etc.
- Embedded distribute lock plugin which manages access to shared resources.
- Metrics server (you might easily expose your own).
- WebSockets and Broadcast via [Centrifugo](https://centrifugal.dev) server.
- Systemd-like services manager with auto-restarts, execution time limiter, etc.
- Production-ready.
- And more 😉

# Join our discord server: [Link](https://discord.gg/TFeEmCs)

<p align="center">
	<a href="https://roadrunner.dev/"><b>Official Website</b></a> |
	<a href="https://docs.roadrunner.dev/"><b>Documentation</b></a> |
    <a href="https://github.com/orgs/roadrunner-server/discussions"><b>Forum</b></a> |
    <a href="https://github.com/orgs/roadrunner-server/projects/4"><b>Release schedule</b></a> |
    <a href="https://gurubase.io/g/roadrunner"><b>Ask RoadRunner Guru</b></a>
</p>

# Installation

The easiest way to get the latest RoadRunner version is to use one of the pre-built release binaries, which are available for
OSX, Linux, FreeBSD, and Windows. Instructions for using these binaries are on the GitHub [releases page](https://github.com/roadrunner-server/roadrunner/releases).

## Docker:

To get the roadrunner binary file you can use our docker image: `ghcr.io/roadrunner-server/roadrunner:2025.X.X` (more information about
image and tags can be found [here](https://github.com/roadrunner-server/roadrunner/pkgs/container/roadrunner)).

```dockerfile
FROM ghcr.io/roadrunner-server/roadrunner:2025.X.X AS roadrunner
FROM php:8.3-cli

COPY --from=roadrunner /usr/bin/rr /usr/local/bin/rr

# USE THE RR
```

Configuration located in the `.rr.yaml` file ([full sample](https://github.com/roadrunner-server/roadrunner/blob/master/.rr.yaml)):


## Installation via Composer
You can also install RoadRunner automatically using the command shipped with the composer package, run:

```bash
composer require spiral/roadrunner-cli
./vendor/bin/rr get-binary
```

Server binary will be available at the root of your project.

> **Note**
>
> PHP's extensions `php-curl` and `php-zip` are required to download RoadRunner automatically.
> PHP's extensions `php-sockets` need to be installed to run roadrunner.
> Check with `php --modules` your installed extensions.


## Installation option for the Debian-derivatives (Ubuntu, Mint, MX, etc)

```bash
wget https://github.com/roadrunner-server/roadrunner/releases/download/v2025.X.X/roadrunner-2025.X.X-linux-amd64.deb
sudo dpkg -i roadrunner-2025.X.X-linux-amd64.deb
```

## Download the latest release via curl:
```bash
curl --proto '=https' --tlsv1.2 -sSf  https://raw.githubusercontent.com/roadrunner-server/roadrunner/master/download-latest.sh | sh
```

## MacOS using [Homebrew](https://brew.sh/):
```bash
brew install roadrunner
```

## Windows using [Chocolatey](https://community.chocolatey.org/):
```bash
choco install roadrunner
```

---

Configuration can be located in `.rr.yaml` file ([full sample](https://github.com/roadrunner-server/roadrunner/blob/master/.rr.yaml)):

```yaml
version: '3'

rpc:
  listen: tcp://127.0.0.1:6001

server:
  command: "php worker.php"

http:
  address: "0.0.0.0:8080"

logs:
  level: error
```

> Read more in [Documentation](https://docs.roadrunner.dev).

Example Worker:
--------

```php
<?php

use Spiral\RoadRunner;
use Nyholm\Psr7;

include "vendor/autoload.php";

$worker = RoadRunner\Worker::create();
$psrFactory = new Psr7\Factory\Psr17Factory();

$worker = new RoadRunner\Http\PSR7Worker($worker, $psrFactory, $psrFactory, $psrFactory);

while ($req = $worker->waitRequest()) {
    try {
        $rsp = new Psr7\Response();
        $rsp->getBody()->write('Hello world!');

        $worker->respond($rsp);
    } catch (\Throwable $e) {
        $worker->getWorker()->error((string)$e);
    }
}
```

> [!IMPORTANT]
> If you see the `EOF` error, check that you have installed the PHP packages from [this step](https://github.com/roadrunner-server/roadrunner#installation-via-composer).
> If this does not help, try to execute the command `php worker.php` directly and check the output.

---

### Available Plugins: [link](https://docs.roadrunner.dev)

Run:
----
To run application server:

```
$ ./rr serve -c .rr.yaml
```

License:
--------
The MIT License (MIT). Please see [`LICENSE`](./LICENSE) for more information. Maintained
by [Spiral Scout](https://spiralscout.com).

## Contributors

Thanks to all the people who already contributed!

<a href="https://github.com/roadrunner-server/roadrunner/graphs/contributors">
  <img src="https://contributors-img.web.app/image?repo=roadrunner-server/roadrunner" />
</a>


RoadRunner

HTTP reverse proxy cache and time series accelerator

# <img src="./docs/images/logos/trickster-logo.svg" width=90 />&nbsp;&nbsp;&nbsp;&nbsp;<img src="./docs/images/logos/trickster-text.svg" width=420 /> [![Follow on Twitter](https://img.shields.io/twitter/follow/trickstercache.svg?style=social&logo=twitter)](https://twitter.com/trickstercache)

[![License](https://img.shields.io/github/license/trickstercache/trickster)](/LICENSE)
[![Coverage Status](https://coveralls.io/repos/github/trickstercache/trickster/badge.svg)](https://coveralls.io/github/trickstercache/trickster)
[![build status](https://github.com/trickstercache/trickster/actions/workflows/ci-build-tests.yml/badge.svg)](https://github.com/trickstercache/trickster/actions/workflows/ci-build-tests.yml)
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/2518/badge)](https://bestpractices.coreinfrastructure.org/en/projects/2518)
[![GoDoc](https://godoc.org/github.com/trickstercache/trickster?status.svg)](https://godoc.org/github.com/trickstercache/trickster)
[![Docker Pulls](https://img.shields.io/docker/pulls/tricksterio/trickster.svg?maxAge=86400)](https://hub.docker.com/r/tricksterio/trickster)

Trickster is an HTTP reverse proxy/cache for http applications and a dashboard query accelerator for time series databases.

<img src="./docs/images/high-level.png" width=512/>

Learn more below, and check out our [roadmap](./docs/roadmap.md) to find out what else is in the works.

Trickster is hosted by the [Cloud Native Computing Foundation](https://cncf.io) (CNCF) as a sandbox level project. If you are a company that wants to help shape the evolution of technologies that are container-packaged, dynamically-scheduled and microservices-oriented, consider joining the CNCF.

Note: Trickster v1.1 is the production release, sourced from the [v1.1.x](https://github.com/trickstercache/trickster/tree/v1.1.x) branch. The `main` branch sources Trickster 2.0, which is currently in beta.

## HTTP Reverse Proxy Cache

Trickster is a fully-featured HTTP Reverse Proxy Cache for HTTP applications like static file servers and web API's.

### Proxy Feature Highlights

* A unique and powerful [Application Load Balancer](./docs/alb.md) for Time Series and generic HTTP endpoints
* [Supports TLS](./docs/tls.md) and HTTP/2 for frontend termination and backend origination
* Offers several options for a [caching layer](./docs/caches.md), including in-memory, filesystem, Redis and bbolt
* [Highly customizable](./docs/configuring.md), using simple yaml configuration settings, [down to the HTTP Path](./docs/paths.md)
* Built-in Prometheus [metrics](./docs/metrics.md) and customizable [Health Check](./docs/health.md) Endpoints for end-to-end monitoring
* [Negative Caching](./docs/negative-caching.md) to prevent domino effect outages
* High-performance [Collapsed Forwarding](./docs/collapsed-forwarding.md)
* Best-in-class [Byte Range Request caching and acceleration](./docs/range_request.md).
* [Distributed Tracing](./docs/tracing.md) via OpenTelemetry, supporting OTLP protocol.
* Rules engine for custom request routing and rewriting
* Configurable [maximum request body size](./docs/body.md).

## Time Series Database Accelerator

Trickster dramatically improves dashboard chart rendering times for end users by eliminating redundant computations on the TSDBs it fronts. In short, Trickster makes read-heavy Dashboard/TSDB environments, as well as those with highly-cardinalized datasets, significantly more performant and scalable.

### Compatibility

Trickster works with virtually any Dashboard application that makes queries to any of these TSDB's:

<img src="./docs/images/external/prom_logo_60.png" width=16 /> Prometheus

<img src="./docs/images/external/clickhouse_logo.png" width=16 /> ClickHouse

<img src="./docs/images/external/influx_logo_60.png" width=16 /> InfluxDB

See the [Supported TSDB Providers](./docs/supported-backend-providers.md) document for full details

### How Trickster Accelerates Time Series

#### 1. Time Series Delta Proxy Cache

Most dashboards request from a time series database the entire time range of data they wish to present, every time a user's dashboard loads, as well as on every auto-refresh. Trickster's Delta Proxy inspects the time range of a client query to determine what data points are already cached, and requests from the tsdb only the data points still needed to service the client request. This results in dramatically faster chart load times for everyone, since the tsdb is queried only for tiny incremental changes on each dashboard load, rather than several hundred data points of duplicative data.

<img src="./docs/images/partial-cache-hit.png" width=1024 />

#### 2. Step Boundary Normalization

When Trickster requests data from a tsdb, it adjusts the clients's requested time range slightly to ensure that all data points returned are aligned to normalized step boundaries. For example, if the step is 300s, all data points will fall on the clock 0's and 5's. This ensures that the data is highly cacheable, is conveyed visually to users in a more familiar way, and that all dashboard users see identical data on their screens.

<img src="./docs/images/step-boundary-normalization.png" width=640 />

#### 3. Fast Forward

Trickster's Fast Forward feature ensures that even with step boundary normalization, real-time graphs still always show the most recent data, regardless of how far away the next step boundary is. For example, if your chart step is 300s, and the time is currently 1:21p, you would normally be waiting another four minutes for a new data point at 1:25p. Trickster will break the step interval for the most recent data point and always include it in the response to clients requesting real-time data.

<img src="./docs/images/fast-forward.png" width=640 />

## Trying Out Trickster

Check out our end-to-end [Docker Compose demo composition](./examples/docker-compose) for a zero-configuration running environment.

## Installing

### Docker

Docker images are available on Docker Hub (docker.io):
```bash
$ docker run --name trickster -d -v /path/to/trickster.yaml:/etc/trickster/trickster.yaml -p 0.0.0.0:8480:8480 trickstercache/trickster
```
Or via  Github Container Registry (ghcr.io):
```bash
    $ docker run --name trickster -d -v /path/to/trickster.yaml:/etc/trickster/trickster.yaml -p 0.0.0.0:8480:8480 ghcr.io/trickstercache/trickster
```
#### Verifying Docker Image

To verify that the Trickster Docker image is running, first walk through the [cosign quickstart guide](https://docs.sigstore.dev/quickstart/quickstart-cosign/).

To verify a trickster image, you can use the following command:

```bash
cosign verify ghcr.io/trickstercache/trickster:x.y.z --certificate-oidc-issuer=https://token.actions.githubusercontent.com --certificate-identity=https://github.com/trickstercache/trickster/.github/workflows/publish-image.yaml@refs/tags/vx.y.z
```


See the 'deploy' Directory for more information about using or creating Trickster docker images.

### Kubernetes

See the 'deploy' Directory for Kube and deployment files and examples.

### Helm

Trickster Helm Charts are located at <https://helm.tricksterproxy.io> for installation, and maintained at <https://github.com/trickstercache/helm-charts>. We welcome chart contributions.

### Building from source

To build Trickster from the source code yourself you need to have a working
Go environment with [version 1.26 or greater installed](http://golang.org/doc/install).

You can directly use the `go` tool to download and install the `trickster`
binary into your `GOPATH`:

```bash
    $ go install github.com/trickstercache/trickster/cmd/trickster@main
    # this starts a prometheus accelerator proxy for the provided endpoint
    $ trickster -origin-url http://prometheus.example.com:9090 -provider prometheus
```

You can also clone the repository yourself and build using `make`:

```bash
    $ mkdir -p $GOPATH/src/github.com/trickstercache
    $ cd $GOPATH/src/github.com/trickstercache
    $ git clone https://github.com/trickstercache/trickster.git
    $ cd trickster
    $ make build
    $ ./bin/trickster -origin-url http://prometheus.example.com:9090 -provider prometheus
```

The Makefile provides several targets, including:

* *build*: build the `trickster` binary
* *docker*: build a docker container for the current `HEAD`
* *clean*: delete previously-built binaries and object files
* *test*: runs unit tests
* *bench*: runs benchmark tests
* *rpm*: builds a Trickster RPM

## More information

* Refer to the [docs](./docs/) directory for additional info.

## Contributing

Refer to [CONTRIBUTING.md](CONTRIBUTING.md)

© 2021 The Linux Foundation. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our [Trademark Usage](https://www.linuxfoundation.org/trademark-usage) page.


Trickster

# Wish

<p>
    <img style="width: 247px" src="https://stuff.charm.sh/wish/wish-header.png" alt="A nice rendering of a star, anthropomorphized somewhat by means of a smile, with the words ‘Charm Wish’ next to it">
    <br>
    <a href="https://github.com/charmbracelet/wish/releases"><img src="https://img.shields.io/github/release/charmbracelet/wish.svg" alt="Latest Release"></a>
    <a href="https://pkg.go.dev/github.com/charmbracelet/wish?tab=doc"><img src="https://godoc.org/github.com/golang/gddo?status.svg" alt="GoDoc"></a>
    <a href="https://github.com/charmbracelet/wish/actions"><img src="https://github.com/charmbracelet/wish/workflows/Build/badge.svg" alt="Build Status"></a>
    <a href="https://codecov.io/gh/charmbracelet/wish"><img alt="Codecov branch" src="https://img.shields.io/codecov/c/github/charmbracelet/wish/main.svg"></a>
    <a href="https://goreportcard.com/report/github.com/charmbracelet/wish"><img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/charmbracelet/wish"></a>
</p>


Make SSH apps, just like that! 💫

SSH is an excellent platform for building remotely accessible applications. It
offers:
* secure communication without the hassle of HTTPS certificates
* user identification with SSH keys
* access from any terminal

Powerful protocols like Git work over SSH and you can even render TUIs directly over an SSH connection.

Wish is an SSH server with sensible defaults and a collection of middlewares that
makes building SSH apps really easy. Wish is built on [gliderlabs/ssh][gliderlabs/ssh]
and should be easy to integrate into any existing projects.

## What are SSH Apps?

Usually, when we think about SSH, we think about remote shell access into servers,
most commonly through `openssh-server`.

That's a perfectly valid (and probably the most common) use of SSH, but it can do so much more than that.
Just like HTTP, SMTP, FTP and others, SSH is a protocol!
It is a cryptographic network protocol for operating network services securely over an unsecured network. [^1]

[^1]: https://en.wikipedia.org/wiki/Secure_Shell

That means, among other things, that we can write custom SSH servers without touching `openssh-server`,
so we can securely do more things than just providing a shell.

Wish is a library that helps writing these kind of apps using Go.

## Middleware

Wish middlewares are analogous to those in several HTTP frameworks.
They are essentially SSH handlers that you can use to do specific tasks,
and then call the next middleware.

Notice that middlewares are composed from first to last,
which means the last one is executed first.

### Bubble Tea

The [`bubbletea`](bubbletea) middleware makes it easy to serve any
[Bubble Tea][bubbletea] application over SSH. Each SSH session will get their own
`tea.Program` with the SSH pty input and output connected. Client window
dimension and resize messages are also natively handled by the `tea.Program`.

You can see a demo of the Wish middleware in action at: `ssh git.charm.sh`

### Git

The [`git`](git) middleware adds `git` server functionality to any ssh server.
It supports repo creation on initial push and custom public key based auth.

This middleware requires that `git` is installed on the server.

### Logging

The [`logging`](logging)  middleware provides basic connection logging. Connects
are logged with the remote address, invoked command, TERM setting, window
dimensions and if the auth was public key based. Disconnect will log the remote
address and connection duration.

### Access Control

Not all applications will support general SSH connections. To restrict access
to supported methods, you can use the [`activeterm`](activeterm) middleware to
only allow connections with active terminals connected and the
[`accesscontrol`](accesscontrol) middleware that lets you specify allowed
commands.

## Default Server

Wish includes the ability to easily create an always authenticating default SSH
server with automatic server key generation.

## Examples

There are examples for a standalone [Bubble Tea application](examples/bubbletea)
and [Git server](examples/git) in the [examples](examples) folder.

## Apps Built With Wish

* [Soft Serve](https://github.com/charmbracelet/soft-serve)
* [Wishlist](https://github.com/charmbracelet/wishlist)
* [SSHWordle](https://github.com/davidcroda/sshwordle)
* [clidle](https://github.com/ajeetdsouza/clidle)
* [ssh-warm-welcome](https://git.coopcloud.tech/decentral1se/ssh-warm-welcome)

[bubbletea]: https://github.com/charmbracelet/bubbletea
[gliderlabs/ssh]: https://github.com/gliderlabs/ssh

## Pro tip

When building various Wish applications locally you can add the following to
your `~/.ssh/config` to avoid having to clear out `localhost` entries in your
`~/.ssh/known_hosts` file:

```
Host localhost
    UserKnownHostsFile /dev/null
```

## How it works?

Wish uses [gliderlabs/ssh][gliderlabs/ssh] to implement its SSH server, and
OpenSSH is never used nor needed — you can even uninstall it if you want to.

Incidentally, there's no risk of accidentally sharing a shell because there's no
default behavior that does that on Wish.

## Running with SystemD

If you want to run a Wish app with `systemd`, you can create an unit like so:

`/etc/systemd/system/myapp.service`:
```service
[Unit]
Description=My App
After=network.target

[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/home/myapp/
ExecStart=/usr/bin/myapp
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

You can tune the values below, and once you're happy with them, you can run:

```bash
# need to run this every time you change the unit file
sudo systemctl daemon-reload

# start/restart/stop/etc:
sudo systemctl start myapp
```

If you use a new user for each app (which is good), you'll need to create them
first:

```bash
useradd --system --user-group --create-home myapp
```

That should do it.

## Contributing

See [contributing][contribute].

[contribute]: https://github.com/charmbracelet/wish/contribute

## Feedback

We’d love to hear your thoughts on this project. Feel free to drop us a note!

* [Twitter](https://twitter.com/charmcli)
* [The Fediverse](https://mastodon.social/@charmcli)
* [Discord](https://charm.sh/chat)

## License

[MIT](https://github.com/charmbracelet/wish/raw/main/LICENSE)

***

Part of [Charm](https://charm.sh).

<a href="https://charm.sh/"><img alt="The Charm logo" src="https://stuff.charm.sh/charm-badge.jpg" width="400"></a>

Charm热爱开源 • Charm loves open source


Wish

[English](https://github.com/bmf-san/gondola) [日本語](https://github.com/bmf-san/gondola/blob/master/README-ja.md)

# Gondola
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
[![GitHub release](https://img.shields.io/github/release/bmf-san/gondola.svg)](https://github.com/bmf-san/gondola/releases)
[![Go Report Card](https://goreportcard.com/badge/github.com/bmf-san/gondola)](https://goreportcard.com/report/github.com/bmf-san/gondola)
[![codecov](https://codecov.io/gh/bmf-san/gondola/branch/main/graph/badge.svg?token=ZLOLQKUD39)](https://codecov.io/gh/bmf-san/gondola)
[![GitHub license](https://img.shields.io/github/license/bmf-san/gondola)](https://github.com/bmf-san/gondola/blob/main/LICENSE)
[![Go Reference](https://pkg.go.dev/badge/github.com/bmf-san/gondola.svg)](https://pkg.go.dev/github.com/bmf-san/gondola)
[![Sourcegraph](https://sourcegraph.com/github.com/bmf-san/gondola/-/badge.svg)](https://sourcegraph.com/github.com/bmf-san/gondola?badge)


A simple and flexible reverse proxy written in Go

## Features
- Lightweight and fast execution
- Simple configuration file (YAML)
- Static file hosting
- Fallback support
- Virtual host support
- Graceful shutdown
- Detailed access logs (nginx-compatible)
- Structured access logs (JSON)
- TLS/SSL support
- Trace ID support
- Timeout control

## Installation

### Go
```bash
go get github.com/bmf-san/gondola
```

### Binary
Download the latest binary from the [Releases](https://github.com/bmf-san/gondola/releases) page.

### Docker
```bash
docker pull bmf-san/gondola
docker run -v $(pwd)/config.yaml:/etc/gondola/config.yaml bmf-san/gondola
```

## Usage

### Command Line Options
```bash
Usage: gondola [options]

Options:
  -config string    Path to configuration file (default: /etc/gondola/config.yaml)
  -version         Display version information
  -help           Show help
```

### Environment Variables
The following environment variables can override command line options:

- `GONDOLA_CONFIG`: Path to the configuration file
- `GONDOLA_LOG_LEVEL`: Log level (debug, info, warn, error)

### Signal Handling
Gondola handles the following signals:

- `SIGTERM`, `SIGINT`: Graceful shutdown
- `SIGHUP`: Reload configuration file
- `SIGUSR1`: Reopen access logs

### Configuration File
```yaml
proxy:
  port: "8080"
  read_header_timeout: 2000  # milliseconds
  shutdown_timeout: 3000     # milliseconds
  log_level: "info"         # debug, info, warn, error
  static_files:
    - path: /public/
      dir: /path/to/public

upstreams:
  - host_name: api.example.com
    target: http://localhost:3000
    read_timeout: 5000      # milliseconds
    write_timeout: 5000     # milliseconds
  - host_name: web.example.com
    target: http://localhost:8000
```

### Startup Examples

Basic startup:
```bash
gondola -config config.yaml
```

Start in debug mode:
```bash
GONDOLA_LOG_LEVEL=debug gondola -config config.yaml
```

Start with Docker:
```bash
docker run -v $(pwd)/config.yaml:/etc/gondola/config.yaml \
          -p 8080:8080 \
          bmf-san/gondola
```

Start with systemd:
```ini
[Unit]
Description=Gondola Reverse Proxy
After=network.target

[Service]
ExecStart=/usr/local/bin/gondola -config /etc/gondola/config.yaml
Restart=always
Environment=GONDOLA_LOG_LEVEL=info

[Install]
WantedBy=multi-user.target
```

## Access Logs

Gondola outputs detailed access logs compatible with nginx.

### Log Fields

1. Client Information
- `remote_addr`: Client IP address
- `remote_port`: Client port number
- `x_forwarded_for`: X-Forwarded-For header

2. Request Information
- `method`: HTTP method (GET, POST, etc.)
- `request_uri`: Full request URI
- `query_string`: Query parameters
- `host`: Host header
- `request_size`: Request size

3. Response Information
- `status`: HTTP status
- `body_bytes_sent`: Response body size
- `bytes_sent`: Total response size
- `request_time`: Request processing time (seconds)

4. Upstream Information
- `upstream_addr`: Backend address
- `upstream_status`: Backend status
- `upstream_size`: Backend response size
- `upstream_response_time`: Backend response time (seconds)

5. Other Headers
- `referer`: Referer header
- `user_agent`: User-Agent header

### Log Output Example
```json
{
  "level": "INFO",
  "msg": "access_log",
  "remote_addr": "192.168.1.100",
  "remote_port": "54321",
  "x_forwarded_for": "",
  "method": "GET",
  "request_uri": "/api/users",
  "query_string": "page=1",
  "host": "api.example.com",
  "request_size": 243,
  "status": "OK",
  "body_bytes_sent": 1532,
  "bytes_sent": 1843,
  "request_time": 0.153,
  "upstream_addr": "localhost:3000",
  "upstream_status": "200 OK",
  "upstream_size": 1532,
  "upstream_response_time": 0.142,
  "referer": "https://example.com",
  "user_agent": "Mozilla/5.0 ...",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

# Projects
- [The gondola's board](https://github.com/users/bmf-san/projects/1/views/1)

# ADR
- [ADR](https://github.com/bmf-san/gondola/discussions?discussions_q=is%3Aopen+label%3AADR)

# Contribution
We welcome issues and pull requests at any time.

Feel free to contribute!

Before contributing, please check the following documents:

- [CODE_OF_CONDUCT](https://github.com/bmf-san/gondra/blob/main/.github/CODE_OF_CONDUCT.md)
- [CONTRIBUTING](https://github.com/bmf-san/gondra/blob/main/.github/CONTRIBUTING.md)

# Sponsors
If you like this project, consider sponsoring us!

[Github Sponsors - bmf-san](https://github.com/sponsors/bmf-san)

Alternatively, giving us a star would be appreciated!

It helps motivate us to continue maintaining this project. :D

# License
This project is licensed under the MIT License.

[LICENSE](https://github.com/bmf-san/gondola/blob/main/LICENSE)

# Stargazers
[![Stargazers repo roster for @bmf-san/gondola](https://reporoster.com/stars/bmf-san/gondola)](https://github.com/bmf-san/gondola/stargazers)

# Forkers
[![Forkers repo roster for @bmf-san/gondola](https://reporoster.com/forks/bmf-san/gondola)](https://github.com/bmf-san/gondola/network/members)

# Author
[bmf-san](https://github.com/bmf-san)

- Email
  - bmf.infomation@gmail.com
- Blog
  - [bmf-tech.com](http://bmf-tech.com)
- Twitter
  - [bmf-san](https://twitter.com/bmf-san)



gondola

A registry for resilient mid-tier load balancing and failover

# Discovery 
[![Build Status](https://travis-ci.org/bilibili/discovery.svg?branch=master)](https://travis-ci.org/bilibili/discovery) 
[![Go Report Card](https://goreportcard.com/badge/github.com/bilibili/discovery)](https://goreportcard.com/report/github.com/bilibili/discovery)
[![codecov](https://codecov.io/gh/Bilibili/discovery/branch/master/graph/badge.svg)](https://codecov.io/gh/Bilibili/discovery)

Discovery is a based service that is production-ready and primarily used at [Bilibili](https://www.bilibili.com/) for locating services for the purpose of load balancing and failover of middle-tier servers.

## Quick Start

### env

`go1.12.x` (and later)

### build
```shell
cd $GOPATH/src
git clone https://github.com/bilibili/discovery.git
cd discovery/cmd/discovery
go build
```

### run
```shell
./discovery -conf discovery.toml -alsologtostderr
```

`-alsologtostderr` is `glog`'s flag，means print into stderr. If you hope print into file, can use `-log.dir="/tmp"`. [view glog doc](https://godoc.org/github.com/golang/glog).

### Configuration

You can view the comments in `cmd/discovery/discovery.toml` to understand the meaning of the config.

### Client

* [API Doc](doc/api.md)
* [Go SDK](naming/client.go) | [Example](naming/example_test.go)
* [Java SDK](https://github.com/flygit/discoveryJavaSDK)
* [CPP SDK](https://github.com/brpc/brpc/blob/master/src/brpc/policy/discovery_naming_service.cpp)
* [Python SDK](https://github.com/tomwei7/discovery-client)
* [other language](doc/sdk.md)

## Intro/Arch/Practice

* [Introduction](doc/intro.md)
* [Architecture](doc/arch.md)
* [Practice in Bilibili](doc/practice.md)

## Feedback

Please report bugs, concerns, suggestions by issues, or join QQ-group 716486124 to discuss problems around source code.


discovery

Nginx log parser and exporter to Prometheus

# Nginx log parser and Prometheus exporter

[![Go Report Card](https://goreportcard.com/badge/github.com/blind-oracle/nginx-prometheus)](https://goreportcard.com/report/github.com/blind-oracle/nginx-prometheus)
[![Coverage Status](https://coveralls.io/repos/github/blind-oracle/nginx-prometheus/badge.svg?branch=master)](https://coveralls.io/github/blind-oracle/nginx-prometheus?branch=master)
[![Build Status](https://travis-ci.org/blind-oracle/nginx-prometheus.svg?branch=master)](https://travis-ci.org/blind-oracle/nginx-prometheus)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go)

This service parses incoming syslog messages from Nginx sent over UDP and converts them into Prometheus metrics exported through the built-in HTTP server.

- If the prefix-list is specified then per-URI statistics are generated.
  Using this feature without URI-prefix list is dangerous because it leads to an unbounded memory usage. It's therefore enabled only with a limited prefix list.

  The URI prefix list is a plain-text file with a single prefix per line, e.g.

  ```bash
  /api/call1.json
  /api/call2.json
  /api/call3.json
  ```

  URIs received from nginx are stripped of any query parameters - only the part before '?' is used.

- It optionally supports country lookup for client IPs using MaxMind GeoIP database.

## Nginx configuration snippet

```nginxconf
log_format collector '$remote_addr|$scheme|$host|$request_method|$server_protocol|$request_uri|$status|$request_time|$request_length|$bytes_sent';
access_log syslog:server=1.1.1.1:1514,tag=nginx collector;
```

## Getting it

- Get RPM & DEB directly from [releases](https://github.com/blind-oracle/nginx-prometheus/releases), only linux-amd64 build currently available.

- Build youself:

```bash
go get github.com/blind-oracle/nginx-prometheus
cd $GOPATH/src/github.com/blind-oracle/nginx-prometheus
go build
```

## Usage example

If you're using RPM/DEB packages then options are set in `/etc/default/nginx-prometheus`

```bash
./nginx-prometheus \
-debug false \
-listenSyslog 0.0.0.0:1514 \
-listenHTTP 0.0.0.0:1514 \
-geoipCountryDB /etc/nginx-prometheus/country.mmdb \
-uriPrefixFile /etc/nginx-prometheus/uriPrefixes.txt
```

- **debug** - prints every syslog message received if true (defaults to false)
- **listenSyslog** - ip:port on which to listen for UDP Syslog messages (defaults to 0.0.0.0:1514)
- **listenHTTP** - ip:port on which to listen for incoming HTTP requests from Prometheus (defaults to 0.0.0.0:11080)
- **geoipCountryDB** - path to MaxMind country GeoIP database (optional)
- **uriPrefixFile** - path to a URI prefix list (optional)

## Grafana dashboard

Add Prometheus source to Grafana and import _grafana-dashboard.json_ for most common graphs.


nginx-prometheus

A (w)eb (d)evelopment server with automatic live-reload on file changes

# (w)eb (d)evelopment-(41)

[![Go Report Card](https://goreportcard.com/badge/github.com/baalimago/wd-41)](https://goreportcard.com/report/github.com/baalimago/wd-41)
[![wakatime](https://wakatime.com/badge/user/018cc8d2-3fd9-47ef-81dc-e4ad645d5f34/project/3bc921ec-dc23-4222-bf00-578f2eda0cbd.svg)](https://wakatime.com/badge/user/018cc8d2-3fd9-47ef-81dc-e4ad645d5f34/project/3bc921ec-dc23-4222-bf00-578f2eda0cbd)

Test coverage: 67.000% 😌👏

This is a simple static webserver which live reloads your web-browser on changes to the hosted files.

## Usage

`wd-41 s|serve <relative directory>` or `wd-41 s|serve` for hosting the current work directory

## Getting started

```bash
go install github.com/baalimago/wd-41@latest
```

You may also use the setup script:

```bash
curl -fsSL https://raw.githubusercontent.com/baalimago/wd-41/main/setup.sh | sh
```

## Architecture

1. First the content of the website is copied to a temporary directory, this is the _mirrored content_
1. Every mirrored file is inspected for type, if it's text/html, a `delta-streamer.js` script is injected
1. The web server is started, hosting the _mirrored_ content
1. The `delta-streamer.js` in turn sets up a websocket connection to the wd-41 webserver
1. The original file system is monitored, on any file changes:
   1. the new file is copied to the mirror (including injections)
   1. the file name is propagated to the browser via the websocket
1. The `delta-streamer.js` script then checks if the current window origin is the updated file. If so, it reloads the page.

```
       ┌───────────────┐
       │ Web Developer │
       └───────┬───────┘
               │
       [writes <content>]
               │
               ▼
 ┌─────────────────────────────┐        ┌─────────────────────┐
 │ website-directory/<content> │        │ file system notify  │
 └─────────────┬───────────────┘        └─────────┬───────────┘
               │                                  │
               │                      [update mirrored content]
               ▼                                  │
     ┌────────────────────┐                       │
     │ ws-script injector │◄──────────────────────┘
     └─────────┬──────────┘
               │
               │
               ▼
   ┌────────────────────────┐
   │ tmp-abcd1234/<content> │
   └───────────┬────────────┘
               │
       [serves <content>]
               │                               ┌────────────────────────┐
               ▼                               │         Browser        │
┌──────────────────────────────┐               │                        │
│          Web Server          │               │  ┌────┐  ┌───────────┐ │
│ [localhost:<port>/<content>] │◄───[reload────┼─►│ ws │  │ <content> │ │
└──────────────────────────────┘     page]     │  └────┘  └───────────┘ │
                                               │                        │
                                               └────────────────────────┘
```


wd-41

lightweight extendable API Gateway in Go - parallel fan-out, flexible aggregation, and zero configuration magic

<h1 align="center">Kono API Gateway</h1>

<p align="center">
A lightweight, modular, and high-performance <strong>API Gateway</strong> for modern microservices.
</p>

<p align="center">
Built with simplicity, performance, and developer-friendly configuration in mind.
</p>

<p align="center">
  <a href="https://golang.org" style="text-decoration: none">
    <img src="https://img.shields.io/badge/go-1.25.4-blue" alt="Go Version"/>
  </a>
  <a href="LICENSE" style="text-decoration: none">
    <img src="https://img.shields.io/github/license/starwalkn/kono" alt="License"/>
  </a>
  <a href="https://goreportcard.com/report/github.com/starwalkn/kono" style="text-decoration: none">
    <img src="https://goreportcard.com/badge/github.com/starwalkn/kono" alt="Go Report Card"/>
  </a>
  <a href="https://codecov.io/gh/starwalkn/kono" style="text-decoration: none">
    <img src="https://codecov.io/gh/starwalkn/kono/branch/master/graph/badge.svg" alt="codecov"/>
  </a>
</p>

---

## ✨ Features

- 🚀 High-performance HTTP reverse proxy
- 🔀 Request fan-out & response aggregation (merge, array, namespace)
- 🧩 Dynamic `.so` plugin system (request & response phase)
- 📜 Lua scripting via **Lumos** (LuaJIT over Unix socket)
- 🔗 Path parameter extraction and forwarding
- 🔁 Retry, circuit breaker & load balancing (round-robin, least-conns)
- 📊 Prometheus metrics with circuit breaker state tracking
- 🛡 Rate limiting & trusted proxy support
- 📦 YAML-based configuration
- 🐳 Docker-ready

---

## 🚀 Quick Start

```bash
git clone https://github.com/starwalkn/kono.git
cd kono

make all GOOS=<YOUR_OS> GOARCH=<YOUR_ARCH>
./bin/kono serve
```

Or with Docker:

```bash
docker run \
  -p 7805:7805 \
  -v $(pwd)/kono.yaml:/app/kono.yaml \
  -e KONO_CONFIG=/app/kono.yaml \
  starwalkn/kono:latest
```

---

## 📖 Documentation

Full documentation, configuration reference, and plugin guide are available at:

**[starwalkn.github.io/konodocs](https://starwalkn.github.io/konodocs/)**

---

## 📄 License

Open-source. See `LICENSE` file for details.

---

<p align="center">
Made with ❤️ in Go
</p>


The Best Go Libraries For Server Applications (31)