One of the often overlooked technical parts of a product are instructions and guidelines on how to operate the product. More specifically, details like server configuration, common commands, and processes for completing work are omitted.
To help you avoid this omission, Pup includes a
README.md template as its own
README.md file that contains some example content you can use for your own product. The
.md part suggests that README is written using Markdown.
In particular, the Pup template suggests outlining:
This section is meant to answer questions like "where is the DNS for the app configured?" or "where does the app live?" These are helpful when onboarding new team members but also as a refresher when you haven't performed certain tasks in awhile.
Settings & Configuration
One of the messier parts of any product is keeping account information like usernames/passwords and configuration organized. This section suggests how to organize settings in the product, how to utilize them, and where to find passwords for accounts related to the management of the product.
This section explains how to get access to the project's dependencies. Typically this is brief, outlining the command for installing dependencies in the app (e.g.,
meteor npm install).
This section details the various NPM scripts and bash commands built into the project that can be used as shortcuts for common tasks (e.g., running tests, performing a deployment, etc.).
Git & Branching
If you're working with others, it's likely that everyone has their own way of working with Git and creating branches. This section is intended to set a standard so that everyone is on the same page and no time is wasted on confusion between each other's processes. It also ensures that you form good habits yourself :)
This section details how to perform tests in the application and what test data exists for that purpose. It also includes information on how to write tests in the app. The goal here is to keep your process consistent and avoid time wasting with folks asking "do we have any tests data for...?"
This section is intended to outline how new code should be released to customers. The goal here is to set a standard process for performing a release, detailing when/how things should be released.
### Product Name A description of the product goes here. 1. Infrastructure 2. Settings & Configuration 3. Dependencies 4. Commands 5. Git & Branching 6. Testing 7. Releasing ### 1. Infrastructure The following explains how the `production` and `staging` environments for this app are managed and configured. #### Where is DNS configured for this app? DNS for the app is configured and managed via [DNSimple](https://dnsimple.com). #### Where does the database live? The database is hosted via [Compose](https://compose.com). A single deployment `cleverbeagle` exists with a `pup` database for the `production` environment and a `pup-staging` database for the `staging` environment. Additionally, the "Oplog Access" add-on has been enabled to [improve the performance of Meteor in `production`](https://galaxy-guide.meteor.com/apm-optimize-your-app-for-oplog.html). #### Where does this app live? The app is deployed to [https://galaxy.meteor.com](https://galaxy.meteor.com). It has two versions: 1. `staging` which is accessed via `https://pup-staging.cleverbeagle.com` and is used to test a release in a production environment _before_ being deployed to `production`. 2. `production` which is accessed via `https://pup.cleverbeagle.com` and is the live, customer-facing server. Deployment to these domains is controlled via NPM scripts defined in the `package.json` file at the root of the project, `npm run staging` and `npm run production`. #### How does the SSL work? SSL certificates are generated via the UI at [https://galaxy.meteor.com/cleverbeagle](https://galaxy.meteor.com/cleverbeagle). Each application's certificates are managed via the app's settings page: - [Staging Server Settings Dashboard](https://galaxy.meteor.com/app/pup-staging.cleverbeagle.com/settings) - [Production Server Settings Dashboard](https://galaxy.meteor.com/app/pup.cleverbeagle.com/settings) SSL certificates are auto-generated by Galaxy using the Let's Encrypt Certificate Authority and shouldn't require any maintenance. If maintenance or edits are required, locate the "Domains & Encryption" section of the app's settings page (linked above) and click on the domain you'd like to manage. ### 2. Settings & Configuration Settings for the app are defined in three files at the root of the project: - `settings-development.json` contains the settings specific to the `development` environment (i.e., when running the app on your computer). - `settings-staging.json` contains the settings specific to the `staging` environmnet (i.e., when deploying the app to `pup-staging.cleverbeagle.com`). - `settings-production.json` contains the settings specific to the `production` environment (i.e., when deploying the app to `pup.cleverbeagle.com`). Each settings file should **_only be used in conjunction with the environment it's intended for_**. Further, each settings file's contents should be restricted to that specific environment (i.e., don't use an API key intended for the `production` environment in `development` and vice-versa—only break this rule when a given service's API key provisioning makes this prohibitive). #### How do I load the settings file? Settings files are automatically loaded for you as part of the NPM commands listed below. It's best to rely on these instead of doing it manually. #### How do I access the accounts used in the settings files? If you need to obtain an API key, password, or other secret information, you can find this in the [Clever Beagle 1Password Vault](https://cleverbeagle.1password.com). If you do not have access to this, send a direct message to @rglover in Slack or email him firstname.lastname@example.org. ### 3. Dependencies Dependencies for `pup.cleverbeagle.com` are installed via NPM and Meteor's Atmosphere package system. Atmosphere dependencies are installed automatically on app startup. NPM dependencies can be installed with the following command **before the first startup of the application**: ``` meteor npm install ``` ### 4. Commands The following NPM commands can be used when working on the app. #### dev ``` $ npm run dev ``` Runs the app development server at `http://localhost:3000` and loads the `settings-development.json` file. #### staging ``` $ npm run staging ``` Deploys the app to the staging server at `https://pup-staging.cleverbeagle.com` and loads the `settings-staging.json` file. #### production ``` $ npm run production ``` Deploys the app to the production server at `https://pup.cleverbeagle.com` and loads the `settings-production.json` file. #### test ``` $ npm run test ``` Runs all [Jest](https://jestjs.io/) test suites in the app once and then quits. #### test-watch ``` $ npm run test-watch ``` Runs all [Jest](https://jestjs.io/) test suites in the app in watch mode and reruns whenever a test or file in the app changes. #### test-e2e ``` $ npm run test-e2e ``` Runs all end-to-end tests using [TestCafe](https://github.com/DevExpress/testcafe) once and then quits. ### 5. Git & Branching [Read the "Managing branches in Git" tutorial in the Pup docs](https://cleverbeagle.com/pup/v2/tutorials/managing-branches-in-git) ### 6. Testing There are two types of testing performed in relation to the app: manual and automated. Manual testing is any testing where you're _manually_ clicking around the app yourself to test things out. Automated testing is any where you're relying on the automated test suites in the app to test things out. #### Test Users When you start the app for the first time in development and staging mode, we create a set of test users to use when testing different permissions: | Email Address | Password | Roles | Notes | |:----------------|:--------:|:-------:|:-------------------------------| | email@example.com | password | `admin` | Full access to the application. | firstname.lastname@example.org | password | `user` | Access to user-only features. | email@example.com | password | `user` | Access to user-only features. | firstname.lastname@example.org | password | `user` | Access to user-only features. | email@example.com | password | `user` | Access to user-only features. | firstname.lastname@example.org | password | `user` | Access to user-only features. #### Test Data When you start the app for the first time, we create test data for all collections in the application. If you ever want to "start over" with fresh data in your `development` environment, stop the app and in your terminal run: ``` meteor reset ``` Upon restarting the app, the databased will be reseeded with the default test data. **FAIR WARNING**: This command will **PERMANENTLY ERASE** (