2021-03-19 15:29:49 +00:00
|
|
|
# Overview
|
|
|
|
|
|
|
|
Legendary is a boilerplate for developing [PETAL-stack](https://changelog.com/posts/petal-the-end-to-end-web-stack)
|
|
|
|
Phoenix/Elixir applications without reinventing the wheel. Out-of-the-box, we
|
|
|
|
include many features that are commonly needed in web applications:
|
|
|
|
|
|
|
|
- Features
|
|
|
|
- Authentication & Authorization
|
|
|
|
- Admin interface & dashboard
|
|
|
|
- Lightweight content management / blogging
|
|
|
|
- Background & scheduled jobs with Oban
|
|
|
|
- Frontend Frameworks
|
|
|
|
- Tailwind CSS
|
|
|
|
- Alpine JS
|
|
|
|
- Fluid HTML email templates
|
|
|
|
- Full CI / DevOps scripts included
|
|
|
|
|
|
|
|
We got tired of setting these things up from scratch on every Phoenix application.
|
|
|
|
So, we built a boilerplate that lets you start with the unique & interesting thing
|
|
|
|
that only your application does. We have a roadmap for future feature development
|
|
|
|
because we still think there are a lot more things we can do to make Phoenix
|
|
|
|
development better.
|
|
|
|
|
|
|
|
## Up and Running
|
|
|
|
|
2021-04-02 22:49:58 +00:00
|
|
|
Since Legendary is both a template and a framework, you can simply clone the repo
|
|
|
|
to start using it. It's a fully functional Phoenix app as-is. To start a new project:
|
|
|
|
|
|
|
|
```sh
|
2021-05-06 17:21:58 +00:00
|
|
|
git clone https://gitlab.com/mythic-insight/legendary.git <project_name>
|
2021-04-02 22:49:58 +00:00
|
|
|
```
|
|
|
|
|
2021-03-19 15:29:49 +00:00
|
|
|
In order to start the server, run `script/server`. Any dependencies required
|
|
|
|
will be installed automatically using [brew](https://brew.sh/),
|
|
|
|
[asdf](https://asdf-vm.com/#/), and [hex](https://hex.pm/).
|
|
|
|
|
|
|
|
Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
|
|
|
|
|
|
|
|
## Development
|
|
|
|
|
2021-04-02 22:49:58 +00:00
|
|
|
Check out [the tutorial](tutorial.md) to learn how to build your first app with
|
|
|
|
Legendary.
|
|
|
|
|
|
|
|
Your main app lives in apps/app/ and you will do most of your
|
2021-03-19 15:29:49 +00:00
|
|
|
development there. This is a normal Phoenix application and you can develop it
|
|
|
|
as such. Any resources which apply to developing Phoenix applications will apply
|
|
|
|
inside of the app. See the [Phoenix Guides](https://hexdocs.pm/phoenix/overview.html)
|
|
|
|
for a good starting resource in Phoenix development.
|
|
|
|
|
|
|
|
You should not generally need to change code in the other applications which
|
2021-04-02 22:49:58 +00:00
|
|
|
are part of the framework-- apps/admin, apps/content, apps/core. We encourage you
|
|
|
|
to avoid changing those as much as possible, because doing so will make it more
|
|
|
|
difficult to upgrade Legendary to newer versions. However, they are available to
|
|
|
|
you if you find that there are no other ways to accomplish the changes that you want.
|
|
|
|
If you find yourself adding functionality to admin, content, or core
|
2021-03-19 15:29:49 +00:00
|
|
|
that you feel would be beneficial to all Legendary apps, consider making a
|
|
|
|
code contribution back to the framework!
|
|
|
|
|
|
|
|
## CI Configuration
|
|
|
|
|
2021-04-02 22:49:58 +00:00
|
|
|
Legendary comes with GitLab CI settings which should work for you with minimal
|
2021-03-19 15:29:49 +00:00
|
|
|
setup.
|
|
|
|
|
|
|
|
The CI script will automatically tag successful builds. To do this, you will
|
2021-04-02 22:49:58 +00:00
|
|
|
need to configure a [CI variable](https://docs.gitlab.com/ee/ci/variables/) named
|
|
|
|
`GITLAB_TOKEN`. This token should be a
|
|
|
|
[personal access token](https://gitlab.com/-/profile/personal_access_tokens) with
|
2021-03-19 15:29:49 +00:00
|
|
|
`read_repository, write_repository` permissions.
|
2021-04-30 22:23:50 +00:00
|
|
|
|
|
|
|
## DevOps
|
|
|
|
|
|
|
|
The preconfigured CI pipeline generates semantically versioned docker images that
|
|
|
|
you can deploy in your choice of dockerized hosting. We also provide a manifest
|
|
|
|
for Kubernetes that is automatically updated with each version (see infrastructure/
|
|
|
|
for the generated result and infrastructure_templates/ for the templates used to
|
|
|
|
generate the manifest).
|