diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile deleted file mode 100644 index 146eb7a..0000000 --- a/.devcontainer/Dockerfile +++ /dev/null @@ -1,8 +0,0 @@ -FROM nicbet/phoenix:1.6.15 - -RUN apt-get install -y ruby \ - && gem install --no-document htmlbeautifier -v 1.3.1 \ - && npm i -g yarn \ - && apt-get autoremove -y \ - && apt-get clean -y \ - && rm -rf /var/lib/apt/lists/* diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index f09a556..bd24d71 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -6,8 +6,8 @@ "forwardPorts": [4000], "shutdownAction": "stopCompose", "extensions": [ - "mjmcloug.vscode-elixir", "jakebecker.elixir-ls", "florinpatrascu.vscode-elixir-snippets", + "phoenixframework.phoenix" ], } \ No newline at end of file diff --git a/.devcontainer/docker-compose.yml b/.devcontainer/docker-compose.yml index 28c8def..db4a4d7 100644 --- a/.devcontainer/docker-compose.yml +++ b/.devcontainer/docker-compose.yml @@ -4,7 +4,7 @@ services: app: build: context: ../ - dockerfile: .devcontainer/Dockerfile + dockerfile: Dockerfile command: sleep infinity environment: - PORT=4000 @@ -16,7 +16,7 @@ services: # should match should match what your application expects. In this case, the # compose file is in a sub-folder, so we will mount '..'. We'll then reference this # as the workspaceFolder in '.devcontainer/devcontainer.json' so VS Code starts here. - - ..:/app:cached + - ../app:/app:cached # This lets you avoid setting up Git again in the container - ~/.gitconfig:/root/.gitconfig diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..b1e5a6f --- /dev/null +++ b/.dockerignore @@ -0,0 +1,3 @@ +.elixir_ls +.vscode +.github \ No newline at end of file diff --git a/.gitignore b/.gitignore index 0f4048b..7247623 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .vscode +.elixir_ls tags -/src \ No newline at end of file +/app \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..acf1caa --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,76 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Accepting constructive criticism with grace +- Focusing on what's best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or + advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic + address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that aren't aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all project spaces, and it also applies when +an individual is representing the project or its community in public spaces. +Examples of representing a project or community include using an official +project e-mail address, posting via an official social media account, or acting +as an appointed representative at an online or offline event. Representation of +a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at opensource@github.com. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality regarding the reporter of an incident. +Further details of specific enforcement policies may be posted in other locations. + +Project maintainers who don't follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html) + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..97ad9c8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,49 @@ +# Contributing + +_Docker Phoenix is intended to be a safe, welcoming space for collaboration. By participating you agree to abide by the [Contributor Code of Conduct](CODE_OF_CONDUCT.md)._ + +Hi there! We're thrilled that you'd like to contribute to Docker Phoenix. Your help is essential for keeping it great! + +If you have any substantial changes that you would like to make, please [open an issue](http://github.com/nicbet/docker-phoenix/issues/new) first to discuss them with us. + +Maintainers tend to focus on areas of the project that are useful to them and their employers, but we're happy to pair with members of the community to enable work on other parts. + +Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [GPLv3 license](https://github.com/nicbet/docker-phoenix/blob/main/LICENSE). + +## Reporting bugs + +When opening an issue to describe a bug, it's helpful to provide steps to reproduce it, either with failing tests in a pull request, or by sharing a repository that demonstrates the issue. + +## Submitting a pull request + +1. [Fork](https://github.com/nicbet/docker-phoenix/fork) and clone the repository. +2. Create a new branch: `git checkout -b my-branch-name`. +3. If it's your first time contributing, add yourself to the `Contributors` section of `README.md`. +4. Push to the fork and [submit a pull request](https://github.com/nicbet/docker-phoenix/compare). +5. Ensure you include a detailed description of your proposed changes. +6. Wait for the pull request to be reviewed and merged. +7. Be on the lookout for review comments and change requests, possibly requiring you to make additional changes to your pull request. + +## Governance + +Docker Phoenix is built by many members of the Open Source community. Project membership has several levels: + +### Triage + +Docker Phoenix **triagers** are able to manage issues and pull request by assigning owners and labels, closing issues and marking duplicates. + +After helping with the project by participating in issues, pull requests, and/or discussions, members of the community are welcome to request triage access by opening a pull request to update this list. + +### Commit + +Docker Phoenix **committers** have `write` access, enabling them to push directly to the repository and merge pull requests, thus removing the need to contribute via a fork. Committers often have implicit ownership over a particular area of the project. + +Triagers are welcome to request commit access by opening a pull request to update this list. + +### Maintain + +Docker Phoenix **maintainers** have `admin` access, enabling them to manage repository settings including access levels. Maintainers are required to have 2FA enabled for their GitHub and Docker Hub accounts. + +Committers are welcome to request maintainership access by opening a pull request to update this list: + +The maintainers team currently consists of: @nicbet. diff --git a/Dockerfile b/Dockerfile index 4ca6135..70388f3 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,15 +1,10 @@ -FROM elixir:1.14.1 +FROM elixir:1.14.1-alpine # Build Args ARG PHOENIX_VERSION=1.6.15 -ARG NODEJS_VERSION=18.x -# Apt -RUN apt-get update && apt-get upgrade -y && apt-get install -y apt-utils build-essential inotify-tools - -# Nodejs -RUN curl -sL https://deb.nodesource.com/setup_${NODEJS_VERSION} | bash -RUN apt-get install -y nodejs +# Apk +RUN apk add bash git inotify-tools nodejs-current npm yarn # Phoenix RUN mix local.hex --force diff --git a/Makefile b/Makefile index da6f841..6036242 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ OWNER = nicbet IMAGE = phoenix TAG = $(OWNER)/$(IMAGE) -VERSION = 1.6.15 +VERSION = 1.6.15-alpine all: test diff --git a/README.md b/README.md index 9ec8ee7..03a7e55 100644 --- a/README.md +++ b/README.md @@ -4,98 +4,71 @@ A dockerized development environment to work on [Elixir](https://github.com/elixir-lang/elixir) and [Phoenix](https://github.com/phoenixframework/phoenix) framework projects while keeping the host environment pristine. -### Background - This project was conceived to deal with the issues of running different Elixir and Phoenix versions and supporting the development and maintenance of apps built with different Elixir and Phoenix versions. Maybe you are working on multiple different projects, built with different versions of the Phoenix framework, or you are working on a long-lived Elixir or Phoenix project. In either case you are likely to hit a version conflict. Phoenix and Elixir are still young und evolving which is great - but some of the changes will likely break your application code. This repository aims to make things easier for you by giving you a straightforward path in swapping out your Elixir and Phoenix environment. -## Getting Started - -To initialize a new development environment, clone this repository. You can specify a version tag to target a particular Phoenix framework version. We automatically pin the Elixir version of each release to the version of Elixir that was available at the time of the specific Phoenix framework release. - -For instance, to set up a dockerized development environment for a project called `hello-phoenix` using Phoenix framework version `1.6.15` you would run: +## Notable Changes -```sh -# Clone this repository into a new project folder -git clone -b 1.6.15 https://github.com/nicbet/docker-phoenix ~/Projects/hello-phoenix +- **#1d570c14007b7750da776e0b6bd2b7568ec67de5** + We've switched the default branch of the repository from `master` to `main`. Please update your local repository refs! -# Go to the new project folder -cd ~/Projects/hello-phoenix +- **Docker Phoenix 1.6.15** + We are currently in the process of switching to `Alpine Linux` based images, which are significantly smaller (~150MB vs 1.7GB). Expect the next release to make `-alpine` the new default for the dev environments. As a result, you will need to rebuild your VSCode dev containers and your application code. -# Initialize a new git repository -rm -rf .git -git init -``` +- **Docker Phoenix 1.6.13** + Starting with this version, we've switched the Docker image hosted at Docker Hub (`docker pull nicbet/phoenix:1.6.13`) to M1 Mac, i.e., `linux/arm64/v8` architecture. If you are developing on an Intel machine, you will need to build the docker image on your platform to get started run `make docker-image`. -## Usage +## Getting Started -You can interact with the containerized dev environment in any way that you would usually interact with a container. We've included a handful of covenience scripts to make running common commands and tools inside the container easier from the host environment. +As of December 2022, we recommend using the [Visual Studio Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) approach over the command line. See below for details. -Our recommended path however is to open the cloned repository in VSCode, following the prompts for starting the `devcontainer` environment. This will give you an editor and a terminal inside the container directly from VSCode. +### Visual Studio Code (Dev Containers) -### New Application +#### Setting up a brand-new project -To create a completely new application from scratch, you can follow these steps: +If you are using a recent version of [Visual Studio Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), we highly recommend going this route for a much improved development experience out of the box. -1. Navigate the to where you cloned this repository, for example: +1. Use [Degit](https://github.com/Rich-Harris/degit) to quickly clone this project as a scaffold for your new project, for example an app called `hello_world`. - ``` - cd ~/Projects/hello-phoenix + ```css + npx degit nicbet/docker-phoenix#1.6.15 hello_world ``` -2. Initialize a new Phoenix application. For example, to create a new Phoenix application called `hello` under the `src/` directory, which is mounted inside the container under `/app` (the default work dir) run: +2. Open the `hello_world` folder in Visual Studio Code - ``` - ./mix phx.new . --app hello - ``` +3. When asked, select `Reopen in container`. Visual Studio code will create a complete application stack including a PostgreSQL database, and mount your local `./app` folder as the root folder for the development environment. - > Why does this work? The `docker-compose.yml` file inlcuded with this repo maps your local `src/` directory to the `/app` directory inside the container. Inside the container, the `/app` directory is marked as the working directory for any command that is being executed, such as `mix phoenix.new`. +4. After initialization of your dev environment finishes, open the `Terminal` tab in Visual Studio Code. -**NOTE:** It is important to specify your app name through the `--app ` option, as Phoenix will otherwise name your app from the target directory passed in, which in our case is `.` +5. Create your new Phoenix application with the following command (**note the `.`**!): -**NOTE:** It is okay to answer `Y` when phoenix states that the `/app` directory already exists. - -**NOTE:** Starting from 1.3.0 the `mix phoenix.new` command has been deprecated. You will have to use the `phx.new` command instead of `phoenix.new` or `mix deps.get` will fail! + ```bash + mix phx.new . hello_world + ``` -### Existing Application +6. As the mix command runs, you will see your Visual Studio Code file explorer populate with the files of your new phoenix app. All these files are available outside your development environment in the `./app` folder. -To use this dev environment with an existing project, follow the steps above to clone this repository and then copy your existing code Phoenix application code to the `/src` directory. The `src/` directory won't exist after cloning this repo so you'll have to create it first with `mkdir -p /src`. +**Note:** You don't need to use `degit`. Alternatively, you can clone this repository and remove the `.git` folder manually. -### Database Connection +#### Configuring the Database Connection -The `docker-compose.yml` file included with this repository defines a servicecalled `db` for running a PostgreSQL database that is available to the main application container via the hostname `db`. By default Phoenix assumes that you are running a database locally. In order to use the `db` service with your application you will need to modify your Phoenix config and point `Ecto` to the database host. +Both, the docker-compose stack started with the `docker-compose.yml` file included with this repository and the Visual Studio Code Dev Containers stack define a service called `db` for running a PostgreSQL database that is available to the main application container via the hostname `db`. By default Phoenix assumes that you are running a database locally. In order to use the `db` service with your application you will need to modify your Phoenix config and point `Ecto` to the database host. -Modify the Ecto configuration `src/config/dev.exs` to point to the DB container: +To use the included database with your phoenix application you will need to modify the Ecto configuration `config/dev.exs` and point it to the DB container: ```elixir # Configure your database config :test, Test.Repo, adapter: Ecto.Adapters.Postgres, + hostname: "db", username: "postgres", password: "postgres", - database: "test_dev", - hostname: "db", + # ... pool_size: 10 ``` -#### Initialize the Database - -When you first start out, the `db` service will contain no databases. To initialize a database for your project, you can run the included convenience script from your host environment: - -```sh -./mix ecto.create -``` - -Then, run your database migrations: - -``` -./mix ecto.migrate -``` - -If you are working inside the dev environment (i.e., using the devcontainer terminal from VSCode), skip the `./` in front of the commands. - -### Starting the Application +#### Running your Application To start you application in development mode you will first need to change your Phoenix configuration to bind the `phx.server` to `0.0.0.0`, so that the container exposes the `phx.server` to the host network. @@ -107,23 +80,19 @@ config :hello_world, HelloWorldWeb.Endpoint, ... ``` -you can run the following command from your host environment: +From the VSCode terminal you can run the Phoenix application server with: ```sh -docker-compose up +mix phx.server ``` -Alternatively, if you just want to run the Phoenix application server you can execute: +Once the startup is completed, your app will be available at http://localhost:4000 -```sh -./mix phx.server -``` +### Using the Command Line instead of Dev Containers -Once booted, it will be available under http://localhost:4000. +After cloning the repository, you can use the included `./run`, `./mix`, `./npm`, and `./yarn` scripts to execute commands in the development environment described by included `docker-compose.yml` file. For instance, running `./mix phx.new . hello_world` would generate a new phoenix application called `hello_world`. Similarly to the Visual Studio Code Dev Containers approach, your project files will be locally stored in the `./app` container which is mounted to `/app` inside the development environment. -## Notes - -### Custom commands +The instructions for changing the database connection and bind address as described above apply here as well. To run any command inside the dev container, you can use the `./run` script and pass the command and its arguments. @@ -139,12 +108,28 @@ You can locally build the container image with the included Makefile: make docker-image ``` -## Support for VS Code Remote Extension +## Usage with an existing project + +You can use this project to dockerize the development enviroment for an existing project. Follow the steps above, but instead of initializing a new application with `mix phx.new`, copy your existing project code to the `./app` subdirectory. This will make your existing code available in the dockerized dev environment. + +## Contributing + +This project is intended to be a safe, welcoming space for collaboration. Contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. We recommend reading the [contributing guide](./docs/CONTRIBUTING.md) as well. + +## License -After cloning this repository, open the folder in Visual Studio Code's Remote Extension to get a full Development Environment (with PostgreSQL Database) spun up automatically. +Docker Phoenix is available as open source under the terms of the [GNU Public License v3](https://www.gnu.org/licenses/gpl-3.0.en.html). -See [https://code.visualstudio.com/docs/remote/containers](https://code.visualstudio.com/docs/remote/containers) for more details. +## Contributors -## Releases with Elixir 1.9+ +Docker Phoenix is built by members of the Open Source community, including: -To prepare a minimal Docker release image based on Alpine Linux (about 38MB for a Phoenix Webapp) you can follow this [Github Gist](https://gist.github.com/nicbet/102f16359828405ce34ca083976986e1). +apenney +cruisemaniac +homanchou +tmr08c +jacknoble +ravloony +asifaly +ajmeese7 +restlessronin diff --git a/docker-compose.yml b/docker-compose.yml index 08336f4..0f09d5d 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -2,12 +2,12 @@ version: "2" services: app: - image: nicbet/phoenix:1.6.15 + image: nicbet/phoenix:1.6.15-alpine build: . ports: - "4000:4000" volumes: - - ./src:/app + - ./app:/app environment: - POSTGRES_USER=postgres - POSTGRES_PASSWORD=postgres diff --git a/yarn b/yarn new file mode 100755 index 0000000..637d764 --- /dev/null +++ b/yarn @@ -0,0 +1 @@ +./run sh -c "cd assets; yarn $@"