Lightweight Koa generator template built with Docker
and docker-compose
to plug and play with a final image size of just ~301MB
.
Heavily based on this generator template.
If you are anything like me, you probably also hate having to download extra tooling just to generate the boilerplate project. With Docker, I can generate the project and then run it using only one tool. I love that! Also, the template has a plug and play philosophy, so it will just work, and I like that too.
To use the generator, you don't need to download/clone anything. Just run the following command:
docker run -v $(pwd):/oahu/base daleal/oahu -n "Project Name"
That will generate a folder named project-name
with your generated project!
The only requirement to run the generator is Docker
. To use the generated application, though, you will also need Compose
(and nothing more).
The requirements for this template are simple:
Docker
Docker Compose
Additionally, to deploy to heroku
you will need:
Heroku
This repo comes with a docker-compose.yml
file to handle using a postgres
image pulled from the web and to use a .env
file for environmental variables. As such, compose
requires a .env
file to function, so run:
cp .env.example .env
After that, configure the .env
file as you please and compose
is now ready to be used.
To get started quickly, build the image:
docker-compose build
Finally, start the server:
docker-compose up
Your app can now be found in localhost:3000
. From now on, every command regarding the app that should be run as [COMMAND]
will now be run as docker-compose run web [COMMAND]
. This includes database migrations (docker-compose run web sequelize db:migrate
).
If you are using Docker
on Linux or Docker
on MacOS, chances are your usage process has been almost flawless, and the instructions given in the tutorial worked at the first try. However, if you are using Docker Toolbox
on Windows or Docker for Windows
on Windows, things are different. Mainly, two things change:
- Due to the technology being run inside a Virtual Machine, instead of finding your app in
localhost:3000
, your app will be defaulted to192.168.99.100:3000
and will not be found inlocalhost:3000
. - Due to the database volume being mounted to a named volume created by the Virtual Machine, every Docker update will wipe your database clean. When using for development purposes, some simple seeds are enough to make this a no-problem. Keep an eye if that is your production environment, though, as data will be lost if you are not careful.
The image generated by docker-compose build
with the original repo has a size of just ~301MB
, and contains a standard Koa app using koa-router
, postgresql
as the database, sequelize
as the ORM, sass
as the stylesheet pre-processor, node 12.16
as the JavaScript runtime and react
as the frontend framework.
The command docker-compose build
must be used only in 2 cases:
- Changes in the
package.json
:docker-compose build
will notice if either thepackage.json
or theyarn.lock
present any changes. If so, it will re-runyarn install
to update the image - New
assets
:docker-compose build
will notice if new assets need to be precompiled and will runwebpack -p
to update the image. This is only relevant on production environments, so don't worry too much about this during development (it is only important to precompile the assets for production environments)
Notice that Docker
is smart and if you run docker-compose build
and the package.json
has not changed and no new assets
need to be precompiled, Docker
will use cached layers to build the image, dramatically decreasing the amount of time wasted in your life (hopefully).
The template includes a GitHub Action to automagically deploy your app to heroku
! On every push to master
(or whenever a Pull Request gets merged into master
), the workflow will trigger and build, push and deploy your app to heroku
, including database migrations! For this magic to work, make sure to do the following stuff:
- Get your
heroku
API Key from yourheroku
dashboard and add it as a GitHub Secret to your repository with a key corresponding toHEROKU_API_KEY
. - Make sure to have a
heroku
app created. Get the app name and add it as a GitHub Secret to your repository with a key corresponding toAPP_NAME
. - Make sure that your app has the
heroku-postgresql
addon provisioned. You can provision it from the dashboard or by runningheroku addons:create heroku-postgresql:hobby-dev -a <appname>
from your terminal, where<appname>
corresponds to the name of yourheroku
app.
So, to sum up, you should have the following GitHub Secrets in your repo:
HEROKU_API_KEY
: your API key forheroku
APP_NAME
: the name of your app inheroku
That's it! Your app should be now deploying automagically!
If you still want to deploy your app manually, you can use the Container Registry. To deploy to heroku
using Container Registry, make sure to be logged in to the platform (heroku login
). Then, log in to Container Registry:
heroku container:login
After that, create a new heroku
app:
heroku create
Don't forget to add the heroku-postgresql
addon to your heroku
app (when deploying to heroku
, only the Rails app will be deployed, and the postgres
container used locally must be replaced with the heroku-postgresql
addon):
heroku addons:create heroku-postgresql:hobby-dev
This command will add the free basic heroku-postgresql
addon to your app (you can upgrade this later if you desire).
Next, build the image and push it to Container Registry:
heroku container:push web
Finally, release the image to your app:
heroku container:release web
Important Note: Once your app is created, to push new changes you only have to run heroku container:push web
and then heroku container:release web
.
To open the app in a browser, you can run heroku open
. You can also access directly using the app's URL.
The template also includes a Pull Request template. That means that every Pull Request's comment will get automagically filled with a default structure that can get altered.