-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update documentation to support dev container setup
- Loading branch information
Showing
4 changed files
with
234 additions
and
154 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,139 @@ | ||
| # Documentation | ||
|
|
||
| ## Getting started | ||
|
|
||
| There are two ways to run set up this application locally. | ||
|
|
||
| - Using VSCode with Dev Containers | ||
| - Installing the dependencies locally and running via Docker Compose | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| - [Docker](https://www.docker.com/) | ||
| - [Docker Compose](https://docs.docker.com/compose/install/) | ||
|
|
||
| ### Using VSCode and Dev Containers | ||
|
|
||
| See [our guide](local-development/vscode-and-devcontainers.md) to get started. | ||
|
|
||
| ### Installing dependencies on your own machine | ||
|
|
||
| See [our guide](local-development/local-installation.md) to get started. | ||
|
|
||
| ## Running tests | ||
|
|
||
| You can run the following in the terminal | ||
|
|
||
| ```shell | ||
| bundle exec rspec | ||
| ``` | ||
|
|
||
| **NOTE:** [If you're using VSCode](local-development/vscode-and-devcontainers.md) you can also run the "bundle exec rspec - run the tests" task. | ||
|
|
||
| When you run the full test suite with the above command a report will be generated by SimpleCov. In the command line on completion of the tests you will see a coverage percentage. | ||
|
|
||
| If you want more indepth understanding of which files are covered: | ||
|
|
||
| ```shell | ||
| open coverage/index.html | ||
| ``` | ||
|
|
||
| ### Dev tips | ||
|
|
||
| - To get Rubocop to fix detected issues automatically (where it can): | ||
|
|
||
| ```shell | ||
| bundle exec rubocop -a | ||
| ``` | ||
|
|
||
| - To run Brakeman locally | ||
|
|
||
| ```shell | ||
| brakeman | ||
| ``` | ||
|
|
||
| - To step through the ignored warnings | ||
|
|
||
| ```shell | ||
| brakeman -I | ||
| ``` | ||
|
|
||
| ## Testing subscription emails | ||
|
|
||
| ### Local dev | ||
|
|
||
| #### Email templates | ||
|
|
||
| When working on email templates, [Action Mailer Previews](https://guides.rubyonrails.org/action_mailer_basics.html#previewing-emails) provide a way to test the output of these templates without having to actually send any emails. We have one set up for subscription lesson emails – example usage: | ||
|
|
||
| <http://localhost:3000/rails/mailers/lesson_mailer/lesson_email?course=how-to-manage-your-money&lesson_no=1&languages=en,ar&disguised=true> | ||
|
|
||
| Note: this preview currently uses the first `User` in the database, so make sure you have one registered locally! | ||
|
|
||
| #### Full subscription email flow | ||
|
|
||
| You can also test out the full subscription email flow locally. We use [mailcatcher](https://github.com/sj26/mailcatcher) to capture all sent email from the local app. An instance of mailcatcher will already be running if you've used the Docker Compose set up mentioned above – you can open this at <http://localhost:1080/>. | ||
| Steps to test: | ||
| 1. Start up the Sidekiq background worker using **(this is not necessary if you're using the Dev Container setup)**: | ||
|
|
||
| ```shell | ||
| bundle exec sidekiq -c 1 | ||
| ``` | ||
|
|
||
| 2. Make or edit a new subscription in the app – make sure the schedule is set accordingly (i.e. to send you an email within the current time slot; note the timezone option, especially if you're currently in daylight savings time). | ||
| 3. Trigger the subscriptions processor: | ||
| ```shell | ||
| bin/rails subscriptions:trigger_worker | ||
| ``` | ||
| 4. Watch the logs for the Sidekiq background worker to see it processing subscriptions and potentially sending out lesson emails. | ||
| 5. Open up the [mailcatcher interface to view all sent emails](http://localhost:1080/). | ||
| ### On Heroku review apps | ||
| By default, newly created review apps on Heroku won't have any of the subscriptions processing and email sending set up. If you do need to test out subscriptions on a review app you can set this up: | ||
|
|
||
| - A Mailgun email service add-on should already be provisioned within the review app – you now need to add your email address to the "allow list" to ensure emails are received: | ||
| - Go to the "Resources" section of your review app in the Heroku console | ||
| - Click on the "Mailgun" add-on – this opens up the Mailgun console | ||
| - Click on "Overview" in the left hand sidebar | ||
| - In the "Authorized Recipients" section of the page, add your email address | ||
| - A confirmation email will be sent to you with an activation link that you'll need to click on | ||
| - Now enable a worker dyno for the Sidekiq background worker: | ||
| - Go to the "Resources" section of your review app in the Heroku console | ||
| - Enable a single worker dyno under the "Hobby Dynos" section | ||
| - Now set up a recurring job to trigger the subscriptions processing: | ||
| - Go to the "Resources" section of your review app in the Heroku console | ||
| - Under "Add-ons" search for "scheduler" and select "Heroku Scheduler", then click on "Provision" | ||
| - Now click on the new "Heroku Scheduler" entry in the list to open it's console | ||
| - Click on "Create job" | ||
| - Schedule for "Every hour at..." ":00" (or a different time point if needed for testing) | ||
| - Set the run command to: `bin/rails subscriptions:trigger_worker` | ||
| - Then click on "Save job" | ||
| - This will run the subscriptions processor on an hourly basis | ||
| - Now you're ready to create subscriptions in that review app instance and receive lesson emails from it | ||
| ## Storyblok content preview mode and caching | ||
| The env var `CONTENT_PREVIEW_MODE` determines the behaviour of content fetches from Storyblok… | ||
| When `CONTENT_PREVIEW_MODE` is set to `true`: | ||
| - **draft** versions of content are fetched | ||
| - content is not cached | ||
| - --> this is useful for review apps and preview environments, for testing the very latest content | ||
| When `CONTENT_PREVIEW_MODE` is set to `false`: | ||
| - only the last **published** versions of content are fetched | ||
| - content is cached in the Redis specified by the env var `REDIS_CACHE_URL` | ||
| - --> so subsequent requests for this data don't need to fetch from Storyblok | ||
| - --> this is important for staging and production environments | ||
| - --> **this means any published content updates may take some time to show up live** (details below) | ||
|
|
||
| The cached content, by default, expires after an hour, after which new published content will be fetched from Storyblok. This expiry can be controlled by the `CONTENT_CACHE_TTL_MINS` env var, if required. | ||
|
|
||
| To flush the cache manually, open up the endpoint `<site_base_url>/admin/flush_cache` in a browser. Now the very latest published content will be fetched from Storyblok. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| # Installing dependencies on your own machine | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - Ruby - see `.ruby-version` for the version required | ||
| - NodeJS - see `package.json` for the version required | ||
| - with Yarn 1.10+ | ||
| - bundler gem ```gem install bundler:1.17.3``` - you need a specific version as version of Ruby is old | ||
| - shared-mime-info a dependency of [mimemagic](https://github.com/mimemagicrb/mimemagic) ```brew install shared-mime-info``` | ||
|
|
||
| ## Dependent services | ||
|
|
||
| [Docker Compose](https://docs.docker.com/compose/overview/) is the recommended way to run all _dependent_ services locally, like the PostgreSQL db and Redis instances. Environment variables in `.env` have been set up to communicate with these services. | ||
|
|
||
| After installing Docker Compose (e.g. using [Docker for Mac](https://docs.docker.com/docker-for-mac/install/)) you can… | ||
|
|
||
| Start all services in the background: | ||
|
|
||
| ```shell | ||
| docker-compose up -d | ||
| ``` | ||
|
|
||
| Shut down all these services: | ||
|
|
||
| ```shell | ||
| docker-compose down | ||
| ``` | ||
|
|
||
| ## Initial Setup | ||
|
|
||
| Once you have the prerequisites above, the codebase cloned and the dependent services running locally… | ||
|
|
||
| Set up **local** env vars in a new `.env.local` file – see the section at the bottom of the `.env` file for the variables you may need to set. | ||
|
|
||
| You will need to ensure your local database has the role "sm" set up with permissions to create databases. | ||
|
|
||
| Then run the following to set everything up: | ||
|
|
||
| ```bash | ||
| bin/setup | ||
| ``` | ||
|
|
||
| ## Running the app locally | ||
|
|
||
| Start up the Rails server with: | ||
|
|
||
| ```shell | ||
| bin/rails server | ||
| ``` | ||
|
|
||
| This serves the app, including all frontend assets (bundled using [Webpack](https://webpack.js.org/)). | ||
|
|
||
| You can **also** run `bin/webpack-dev-server` in a separate terminal shell if you want live reloading (in your browser) of CSS and JavaScript changes (note: only changes made within the `app/webpack` folder will cause live reloads). | ||
|
|
||
| (optionally) Start up the background processor with: | ||
|
|
||
| ```shell | ||
| bundle exec sidekiq -c 1 | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| # Using VSCode and Dev Containers | ||
|
|
||
| > The **Visual Studio Code Dev Containers** extension lets you use a container as a full-featured development environment. It allows you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code's full feature set. | ||
| See <[devcontainer-documentation]> for more information. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - Meet the [system requirements](https://code.visualstudio.com/docs/devcontainers/containers#_system-requirements) | ||
| - Follow the [installation instructions](https://code.visualstudio.com/docs/devcontainers/containers#_installation) | ||
| - [Check the installation](https://code.visualstudio.com/docs/devcontainers/tutorial#_check-installation) | ||
|
|
||
| ## Initial setup | ||
|
|
||
| After you've verified that the extension is installed and working, click on the "Remote Status" bar icon and select | ||
| "Reopen in Container". | ||
|
|
||
| Once your machine is built and running you'll need to make sure to update the `.env.local` file with the required | ||
| credentials. These are _essential_ to running the application. | ||
|
|
||
| ## Running the app | ||
|
|
||
| In this project, we use [tasks](https://code.visualstudio.com/docs/editor/tasks) to make the experience easier | ||
| when using VSCode. | ||
|
|
||
| Click on "Terminal" -> "Run Task" -> "bin/server - run the server" | ||
|
|
||
| We use [`overmind`](https://github.com/DarthSim/overmind) to start up all of the required processes defined in | ||
| `Procfile.dev`. | ||
|
|
||
| Your application will be viewable at <http://localhost:3000>. | ||
|
|
||
| [devcontainer-documentation]: https://code.visualstudio.com/docs/devcontainers/container |