{"id":13786703,"url":"https://github.com/appable-run/appy","last_synced_at":"2025-07-11T20:31:05.086Z","repository":{"id":45773218,"uuid":"188772640","full_name":"appable-run/appy","owner":"appable-run","description":"An opinionated productive web framework that helps scaling business easier.","archived":false,"fork":false,"pushed_at":"2024-03-07T17:15:23.000Z","size":5448,"stargazers_count":132,"open_issues_count":5,"forks_count":13,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-07-05T10:58:24.826Z","etag":null,"topics":["12factor","docker","full-stack","golang","graphql","mailer","prerender","sveltekit","worker"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appable-run.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support/array.go","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"cayter"}},"created_at":"2019-05-27T04:48:59.000Z","updated_at":"2024-08-02T05:38:11.000Z","dependencies_parsed_at":"2024-01-08T16:08:44.299Z","dependency_job_id":"b53399f5-8f57-40e0-8721-75c57c369e2f","html_url":"https://github.com/appable-run/appy","commit_stats":null,"previous_names":["appable-run/appy","appablejs/appy","appist/appy"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/appable-run/appy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appable-run%2Fappy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appable-run%2Fappy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appable-run%2Fappy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appable-run%2Fappy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appable-run","download_url":"https://codeload.github.com/appable-run/appy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appable-run%2Fappy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264892068,"owners_count":23679217,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["12factor","docker","full-stack","golang","graphql","mailer","prerender","sveltekit","worker"],"created_at":"2024-08-03T19:01:29.506Z","updated_at":"2025-07-11T20:31:01.133Z","avatar_url":"https://github.com/appable-run.png","language":"Go","readme":"\u003cp align=\"center\"\u003e\u003cimg src=\".github/assets/logo.png\" width=\"180\"\u003e\u003c/p\u003e\n\n# appy\n\n[![Build Status](https://github.com/appist/appy/workflows/Unit%20Test/badge.svg)](https://github.com/appist/appy/actions?workflow=Unit+Test)\n[![Vulnerabilities Check](https://github.com/appist/appy/workflows/Vulnerabilities%20Check/badge.svg)](https://github.com/appist/appy/actions?workflow=Vulnerabilities+Check)\n[![Go Report Card](https://goreportcard.com/badge/github.com/appist/appy)](https://goreportcard.com/report/github.com/appist/appy)\n[![Coverage Status](https://img.shields.io/codecov/c/gh/appist/appy.svg?logo=codecov)](https://codecov.io/gh/appist/appy)\n[![Go Doc](http://img.shields.io/badge/godoc-reference-5272B4.svg)](https://pkg.go.dev/github.com/appist/appy?tab=doc)\n[![Platform Support](https://img.shields.io/badge/platform-macos%20%7C%20linux%20%7C%20windows-blue)](https://github.com/appist/appy)\n\nAn opinionated productive web framework that helps scaling business easier, i.e. focus on monolith first, only move to microservices with [GRPC](https://grpc.io/) later on when your team is ready.\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick to see an application called \"appist\" made with \"appy\" in action\u003c/summary\u003e\n\n  \u003cp align=\"center\"\u003e\n    \u003cimg width=\"48%\" alt=\"Debug Mode\" src=\".github/assets/debug.gif\"\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n    \u003cimg width=\"48%\" alt=\"Release Mode\" src=\".github/assets/release.gif\"\u003e\n  \u003c/p\u003e\n\u003c/details\u003e\n\n#### Additional Notes\n\n- `appy` is made as a package for your application to import without the need to install any additional binary\n- `appy` glues the [great packages](#acknowledgement) to provide best productivity in developing Go web application\n- `appy` comes with 2 build types:\n  - debug - when the code is NOT running within the binary\n  - release - when the code is running within the binary\n- `appy` follows [12factor](https://12factor.net/) via `APPY_ENV` environment variable:\n  - by default, it is `development`\n  - when `APPY_ENV=staging` is set, the config file is `configs/.env.staging`\n  - utilise `configs/.env.\u003cAPPY_ENV\u003e` to support multiple environments deployment\n\n## Table Of Contents\n- [Overview](#overview)\n- [Features](#features)\n  - [package `cmd`](#package-cmd)\n  - [package `mailer`](#package-mailer)\n  - [package `pack`](#package-pack)\n  - [package `record`](#package-record)\n  - [package `view`](#package-view)\n  - [package `worker`](#package-worker)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Quick Start](#quick-start)\n- [Acknowledgement](#acknowledgement)\n- [Contribution](#contribution)\n- [License](#license)\n\n## Overview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg height=\"450px\" alt=\"architecture\" src=\"./.github/assets/architecture.png\" /\u003e\n\u003c/p\u003e\n\n## Features\n\n### package `cmd`\n\n- Powerful built-in commands\n  \u003cdetails\u003e\n    \u003csummary\u003eClick to see details\u003c/summary\u003e\n\n  ```bash\n  My first awesome web application in Go.\n\n  Usage:\n    myapp [command]\n\n  Available Commands:\n    build             Compile the static assets into go files and build the release build binary (only available in debug build)\n    config:dec        Decrypt a config value using the secret in `configs/\u003cAPPY_ENV\u003e.key` or `APPY_MASTER_KEY` (only available in debug build)\n    config:enc        Encrypt a config value using the secret in `configs/\u003cAPPY_ENV\u003e.key` or `APPY_MASTER_KEY` (only available in debug build)\n    db:create         Create all databases for the current environment\n    db:drop           Drop all databases for the current environment\n    db:migrate        Migrate the database(default: all, use --database to specify the target database) for the current environment\n    db:migrate:status List all the database migration status(default: all, use --database to specify the target database) for the current environment\n    db:rollback       Rollback the database(default: primary, use --database to specify the target database) to previous version for the current environment\n    db:schema:dump    Dump all the databases schema for the current environment (only available in debug build)\n    db:schema:load    Load all the databases schema for the current environment\n    db:seed           Seed all databases for the current environment\n    dc:down           Tear down the docker compose cluster\n    dc:restart        Restart services that are defined in `docker-compose.yml`\n    dc:up             Create and start containers that are defined in `docker-compose.yml`\n    gen:migration     Generate database migration file(default: primary, use --database to specify the target database) for the current environment (only available in debug build)\n    help              Help about any command\n    middleware        List all the global middleware\n    routes            List all the server-side routes\n    secret            Generate a cryptographically secure secret key for encrypting cookie, CSRF token and config\n    secret:rotate     Rotate the secret that is used to encrypt/decrypt the configs (only available in debug build)\n    serve             Run the HTTP/HTTPS web server without `webpack-dev-server`\n    setup             Run dc:up/db:create/db:schema:load/db:seed to setup the datastore with seed data\n    ssl:setup         Generate and install the locally trusted SSL certs using `mkcert`\n    ssl:teardown      Uninstall the locally trusted SSL certs using `mkcert`\n    start             Run the HTTP/HTTPS web server with `webpack-dev-server` in development watch mode (only available in debug build)\n    teardown          Tear down the docker compose cluster\n    work              Run the worker to process background jobs\n\n  Flags:\n    -h, --help      help for myapp\n    -v, --version   version for myapp\n\n  Use \"myapp [command] --help\" for more information about a command.\n  ```\n\n  \u003c/details\u003e\n\n- Flexible custom commands building\n\n### package `mailer`\n\n- Ready-to-use SMTP email sending\n\n- I18n support\n\n- HTML templates binary embed support\n\n- Developer friendly email preview UI\n  \u003cdetails\u003e\n    \u003csummary\u003eClick to see details\u003c/summary\u003e\n\n    \u003cp align=\"center\"\u003e\n      \u003cimg height=\"450px\" alt=\"Preview UI\" src=\"./.github/assets/mailer_preview_ui.png\" /\u003e\n    \u003c/p\u003e\n  \u003c/details\u003e\n\n### package `pack`\n\n- Powerful built-in HTTP middleware\n  \u003cdetails\u003e\n    \u003csummary\u003eClick to see details\u003c/summary\u003e\n\n  - API Only\u003cbr\u003e\n    Remove `Set-Cookie` response header if the `X-API-ONLY: 1` request header is sent.\n\n  - CSRF\u003cbr\u003e\n    Protect cookies from `Cross-Site Request Forgery` by including/validating a token in the cookie across requests.\n\n  - GZIP Compress\u003cbr\u003e\n    Compress the responses before returning it to the clients.\n\n  - Health Check\u003cbr\u003e\n    Provide the HTTP GET endpoint for health check purpose.\n\n  - I18n\u003cbr\u003e\n    Provide I18n support which the translations are stored in `\u003cPROJECT_NAME\u003e/pkg/locales/*.yml`.\n\n  - Logger\u003cbr\u003e\n    Provide logger support.\n\n  - Mailer\u003cbr\u003e\n    Provide mailer support which the views templates are stored in `\u003cPROJECT_NAME\u003e/pkg/views/mailers/**/*.{html,txt}`.\n\n  - Prerender\u003cbr\u003e\n    Prerender and return the SPA page rendered by Chrome if the HTTP request is coming from the search engines.\n\n  - Real IP\u003cbr\u003e\n    Retrieves the client's real IP address via `X-FORWARDED-FOR` or `X-REAL-IP` HTTP request header.\n\n  - Recovery\u003cbr\u003e\n    Recover the HTTP request from panic and return 500 error page.\n\n  - Request ID\u003cbr\u003e\n    Generate UUID v4 string for every HTTP request.\n\n  - Request Logger\u003cbr\u003e\n    Log the HTTP request information.\n\n  - Secure\u003cbr\u003e\n    Provide the standard HTTP security guards.\n\n  - Session\u003cbr\u003e\n    Provide session management using cookie/redis.\n\n  - SPA\u003cbr\u003e\n    Provide SPA hosting with specific path.\n\n  - View Engine\u003cbr\u003e\n  Provide server-side HTML template rendering.\n  \u003c/details\u003e\n\n- Fully integrated with [gqlgen](https://gqlgen.com/) with watch mode\n\n- Ready-to-use test context builder for unit test\n\n### package `record`\n\n- Powerful database management commands\n  \u003cdetails\u003e\n    \u003csummary\u003eClick to see details\u003c/summary\u003e\n\n  ```bash\n  db:create         Create all databases for the current environment\n  db:drop           Drop all databases for the current environment\n  db:migrate        Migrate the database(default: all, use --database to specify the target database) for the current environment\n  db:migrate:status List all the database migration status(default: all, use --database to specify the target database) for the current environment\n  db:rollback       Rollback the database(default: primary, use --database to specify the target database) to previous version for the current environment\n  db:schema:dump    Dump all the databases schema for the current environment (only available in debug build)\n  db:schema:load    Load all the databases schema for the current environment\n  db:seed           Seed all databases for the current environment\n  ```\n\n  \u003c/details\u003e\n\n- Extended `sql.DB` with [sqlx](https://github.com/jmoiron/sqlx)\n\n- Fully featured ORM\n  \u003cdetails\u003e\n    \u003csummary\u003eClick to see details\u003c/summary\u003e\n\n  - Multiple databases support\n  - Master/Replica switch\n  - Soft delete\n  - Associations (Not Yet Supported)\n    - Has One\n    - Has Many\n    - Belongs To\n    - Many To Many\n    - Polymorphism\n    - Preload\n    - Eager Load\n  - Callbacks\n    - BeforeValidate/AfterValidate\n    - BeforeCreate/AfterCreate\n    - BeforeDelete/AfterDelete\n    - BeforeUpdate/AfterUpdate\n    - BeforeCommit/AfterCreateCommit/AfterDeleteCommit/AfterUpdateCommit\n    - BeforeRollback/AfterRollback\n  - Composite primary keys\n  - Execution with context\n  - SQL query builder/logger/inspector\n  - Transactions\n  - Validations with I18n support\n  \u003c/details\u003e\n\n- Performant ORM\n  \u003cdetails\u003e\n    \u003csummary\u003eClick to see details\u003c/summary\u003e\n\n  ```bash\n  go test -run=NONE -bench . -benchmem -benchtime 10s -failfast ./record\n  goos: darwin\n  goarch: amd64\n  pkg: github.com/appist/appy/record\n  BenchmarkInsertRaw-4                1239          10103533 ns/op              88 B/op          5 allocs/op\n  BenchmarkInsertDB-4                  898          11351591 ns/op            1548 B/op         19 allocs/op\n  BenchmarkInsertORM-4                 826          13826999 ns/op           15338 B/op        283 allocs/op\n  BenchmarkInsertMultiRaw-4            529          21830643 ns/op          107896 B/op        415 allocs/op\n  BenchmarkInsertMultiDB-4             481          20931749 ns/op          166302 B/op        441 allocs/op\n  BenchmarkInsertMultiORM-4            471          23261618 ns/op          791677 B/op       3872 allocs/op\n  BenchmarkUpdateRaw-4                 903          13807008 ns/op            1064 B/op         21 allocs/op\n  BenchmarkUpdateDB-4                 1008          13577352 ns/op            3677 B/op         52 allocs/op\n  BenchmarkUpdateORM-4                 788          13923442 ns/op            8920 B/op        233 allocs/op\n  BenchmarkReadRaw-4                  2162           4723198 ns/op            1810 B/op         47 allocs/op\n  BenchmarkReadDB-4                   2263           5300805 ns/op            3257 B/op         69 allocs/op\n  BenchmarkReadORM-4                  2259           5184327 ns/op            6911 B/op        230 allocs/op\n  BenchmarkReadSliceRaw-4             2210           5871991 ns/op           23088 B/op       1331 allocs/op\n  BenchmarkReadSliceDB-4              2197           5752959 ns/op           25070 B/op       1353 allocs/op\n  BenchmarkReadSliceORM-4             1864           6249231 ns/op          246630 B/op       1526 allocs/op\n  PASS\n  ok      github.com/appist/appy/record   344.692s\n  ```\n\n  \u003c/details\u003e\n\n- Ready-to-use DB/ORM mocks for unit test\n\n### package `view`\n\n- Performant and fully featured [template engine](https://github.com/CloudyKit/jet)\n\n- I18n support\n\n- HTML templates binary embed support\n\n### package `worker`\n\n- Fully featured background job processing backed by Redis\n  \u003cdetails\u003e\n    \u003csummary\u003eClick to see details\u003c/summary\u003e\n\n  - Cron jobs (Work In Progress)\n  - Expiring jobs\n  - Unique jobs\n  - Scheduled jobs\n  - Error handling\n  - Middleware\n  - Responsive Web UI + Authorization + Search (Work In Progress)\n  - Strict/Weighted priority queues\n  \u003c/details\u003e\n\n- Ready-to-use handler mock for unit test\n\n## Getting Started\n\n### Prerequisites\n\n- [Docker \u003e= 19](https://www.docker.com/products/docker-desktop)\n- [Docker Compose \u003e= 1.13](https://docs.docker.com/compose/install)\n- [Go \u003e= 1.14](https://golang.org/dl/)\n- [NodeJS \u003e= 14](https://nodejs.org/en/download/)\n- [PostgreSQL \u003e= 11](https://www.postgresql.org/download/)\n- [MySQL \u003e= 8](https://www.mysql.com/downloads/)\n\n### Quick Start\n\n#### Step 1: Create the project folder with go module and git initialised.\n\n```bash\n$ mkdir \u003cPROJECT_NAME\u003e \u0026\u0026 cd $_ \u0026\u0026 go mod init $_ \u0026\u0026 git init\n```\n\n\u003e Note: The \u003cPROJECT_NAME\u003e must be an alphanumeric string.\n\n#### Step 2: Create `main.go` with the snippet below.\n\n```go\npackage main\n\nimport (\n  \"github.com/appist/appy/cmd\"\n)\n\nfunc main() {\n  err := cmd.Scaffold()\n\n  if err != nil {\n    panic(err)\n  }\n}\n```\n\n#### Step 3: Initialize the project layout.\n\n```bash\n$ go run .\n```\n\n#### Step 4: Setup the databases using Docker Compose.\n\n```bash\n$ go run . setup\n```\n\n#### Step 5: Start developing your application locally.\n\n```bash\n$ go run . start\n```\n\n## Acknowledgement\n\n- [asynq](https://github.com/hibiken/asynq) - For processing background jobs\n- [cobra](https://github.com/spf13/cobra) - For building CLI\n- [gin](https://github.com/gin-gonic/gin) - For building HTTP router\n- [gqlgen](https://gqlgen.com/) - For building GraphQL API\n- [sqlx](https://github.com/jmoiron/sqlx) - For interacting with MySQL/PostgreSQL\n- [testify](https://github.com/stretchr/testify) - For writing unit tests\n- [zap](https://github.com/uber-go/zap) - For blazing fast, structured and leveled logging\n\n## Contribution\n\nPlease make sure to read the [Contributing Guide](https://github.com/appist/appy/blob/master/.github/CONTRIBUTING.md) before making a pull request.\n\nThank you to all the people who already contributed to appy!\n\n## License\n\n[MIT](http://opensource.org/licenses/MIT)\n\nCopyright (c) 2019-present, Appist\n","funding_links":["https://github.com/sponsors/cayter"],"categories":["Web Frameworks"],"sub_categories":["Fail injection"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappable-run%2Fappy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappable-run%2Fappy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappable-run%2Fappy/lists"}