Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update docs #1012

Merged
merged 4 commits into from
Jan 25, 2019
Merged

Update docs #1012

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b8d2170
Update docs
kpuputti Jan 25, 2019
87d488d
Add changelog entry
kpuputti Jan 25, 2019
53f8bb3
Re-run Prettier with updated dependencies
kpuputti Jan 25, 2019
5f07959
Fix changelog entry
kpuputti Jan 25, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ way to update this template, but currently, we follow a pattern:

## Upcoming version 2019-XX-XX

- [change] Some of the documentation moved to Flex Docs: https://www.sharetribe.com/docs/
[#1012](https://github.com/sharetribe/flex-template-web/pull/1012)
- [fix] Allow ownListing as listing proptype in BookingPanel component.
[#1007](https://github.com/sharetribe/flex-template-web/pull/1007)
- [add] Add info text about additional owners to `PayoutDetailsForm`.
Expand Down
9 changes: 7 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,13 @@ yarn run config # add the mandato
yarn run dev # start the dev server, this will open a browser in localhost:3000
```

See the [Environment configuration variables](docs/env.md) documentation for more information of the
required configuration variables.
You can also follow along the
[Getting started with FTW](https://www.sharetribe.com/docs/tutorials/getting-started-with-ftw/)
tutorial in the [Flex Docs website](https://www.sharetribe.com/docs/).

For more information of the configuration, see the
[FTW Environment configuration variables](https://www.sharetribe.com/docs/references/ftw-env/)
reference in Flex Docs.

**Note:** If you want to build your own Flex marketplace on top of the template, you should fork the
repository instead of cloning it. See the [Customization guide](./docs/customization-guide.md).
Expand Down
32 changes: 28 additions & 4 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,24 @@ Marketplace features included in Saunatime:
- **User profiles** provide detailed information about a given user.
- **Extended data:** The listing and user data models are modified using extended data.

## Flex Docs website

We are currently moving documentation to the Flex Docs site, so at the moment part of the
documentation is in this repository and part is in the Flex Docs site.

See the Flex Docs site: https://www.sharetribe.com/docs/

## Getting started

We recommend going through the
[Getting started articles](https://www.sharetribe.com/docs/background/getting-started/) in the Flex
Docs:

- [Introducing Flex](https://www.sharetribe.com/docs/background/introducing-flex/)
- [What development skills are needed?](https://www.sharetribe.com/docs/background/development-skills/)
- [Getting started with FTW](https://www.sharetribe.com/docs/tutorials/getting-started-with-ftw/)
tutorial.

## How to customize this template

The easiest way to start a customization project is to read through the
Expand All @@ -35,27 +53,33 @@ Documentation for specific topics can be found in the following files:

- [Customization guide](customization-guide.md)
- [Folder structure](folder-structure.md)
- [Integration to map providers](map-providers.md)
- [Translations](translations.md)
- [Styling a marketplace](styling.md)
- [Static pages](static-pages.md)
- [Terms of Service and Privacy Policy](terms-of-service-and-privacy-policy.md)
- [Routing](routing.md)
- [Redux and duck files](redux.md)
- [Extended data](extended-data.md)
- See also the
[Extended data reference](https://www.sharetribe.com/docs/references/extended-data/) in Flex
Docs
- [Extend the listing data model](extend-listing.md)
- [Search filters](search-filters.md)
- [Testing](testing.md)
- [Error logging with Sentry](sentry.md)
- [Analytics](analytics.md)
- [Continuous Integration (CI)](ci.md)
- [Content Security Policy (CSP)](content-security-policy.md)
- [Original create-react-app documentation](https://github.com/sharetribe/create-react-app/blob/master/packages/react-scripts/template/README.md)
- [Customization checklist](customization-checklist.md)
- [Icons](icons.md)
- [Improving performance](improving-performance.md)
- [Deploying to production](deploying-to-production.md)

See also the following articles in the [Flex Docs](https://www.sharetribe.com/docs/) website:

- [How to set up Mapbox for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-mapbox-for-ftw/)
- [How to set up Sentry to log errors in FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-sentry-to-log-errors-in-ftw/)
- [How to set up Analytics for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-analytics-for-ftw/)
- [How to set up Content Security Policy (CSP) for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-csp-for-ftw/)

The application was bootstrapped with a forked version of
[create-react-app](https://github.com/facebookincubator/create-react-app). While most of the
original documentation still applies, there are some important differences listed in the
Expand Down
36 changes: 2 additions & 34 deletions docs/analytics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,37 +1,5 @@
# Analytics

The application supports tracking page views with pluggable analytics handlers.
Documentation moved to the Flex Docs site:

## Google Analytics

Google Analytics (GA) is supported by default. The enable GA, set the GA tracker ID to the
environment variable `REACT_APP_GOOGLE_ANALYTICS_ID`;

## Custom analytics handler

If you want to add a new analytics library, you can do as follows:

1. Add the analytics library script

If the analytics library has an external script, add the library script tag to the
[src/public/index.html](../public/index.html) file. If you need more control, see how the GA
script is added in [server/renderer.js](../server/renderer.js).

1. Create a handler

To track page views, create a custom handler e.g. in
[src/analytics/handlers.js](../src/analytics/handlers.js). The handler should be a class that
implements a `trackPageView(url)` method.

Note that the `url` parameter might not be the same as in the URL bar of the browser. It is the
canonical form of the URL. For example, in the listing page it doesn't have the dynamic title
slug in the middle. This allows unified analytics and correct tracking of pages that can be
accessed from multiple different URLs.

If you analytics library takes the page URL from the browser, you might need to override that
behavior to use the canonical URL that is given to the method.

1. Initialise the handler

Initialise the handler in the `setupAnalyticsHandlers()` function in
[src/index.js](../src/index.js).
https://www.sharetribe.com/docs/guides/how-to-set-up-analytics-for-ftw/
42 changes: 2 additions & 40 deletions docs/content-security-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,5 @@
# Content Security Policy (CSP)

According to [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP):
Documentation moved to the Flex Docs site:

> Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate
> certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks. These
> attacks are used for everything from data theft to site defacement or distribution of malware.

This document describes how to use a CSP with the Flex template app. By default the CSP is disabled.
By turning it on, the default whitelist in [server/csp.js](../server/csp.js) works with the all the
URLs and tools that come with the application.

## Setup

The CSP is configured using the `REACT_APP_CSP` environment variable.

Possible values:

- not set: disabled
- `REACT_APP_CSP=report`: Enabled, but policy violations are only reported
- `REACT_APP_CSP=block`: Enabled. Policy violations are reported and requests that violate the
policy are blocked

If error logging with Sentry is enabled (See [Error logging with Sentry](sentry.md)), the reports
are sent to Sentry. Otherwise the reports are just logged in the backend.

## Extending the policy

If you want to whitelist new sources (for example adding a new external analytics service) and keep
the CSP enabled, you should add the domains to the white list in [server/csp.js](../server/csp.js).

The easiest way to do this is to first turn on the policy in report mode and then see what policy
violations are logged to the browser developer console or to the backend policy violation report
URL.

## Resources

To understand what CSP is and how browsers work, here are some resources:

- https://content-security-policy.com/
- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
- https://ponyfoo.com/articles/content-security-policy-in-express-apps
- https://helmetjs.github.io/docs/csp/
https://www.sharetribe.com/docs/guides/how-to-set-up-csp-for-ftw/
2 changes: 2 additions & 0 deletions docs/customization-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@ Some generic things to update and check when starting to customize the template.
- Update [routeConfiguration](../src/routeConfiguration.js) if needed
- Update [Email templates](../ext/default-mail-templates), all of them: .html, subject.txt, and
text.txt
- See the [Email template reference](https://www.sharetribe.com/docs/references/email-templates/)
in Flex Docs for more information.
- Update [config: bookingUnitType](../src/config.js) if needed
- If `line-item/units` is used, add quantity handling to
[BookingDatesForm](../src/forms/BookingDatesForm/BookingDatesForm.js),
Expand Down
16 changes: 14 additions & 2 deletions docs/customization-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,17 @@ will help you in setting up your fork and describes the general workflow.
README file, you probably don't want to make the customizations in that project. Forking the
repository is the recommended way to proceed. Follow this guide for instructions.

## Getting started

We recommend going through the
[Getting started articles](https://www.sharetribe.com/docs/background/getting-started/) in the Flex
Docs:

- [Introducing Flex](https://www.sharetribe.com/docs/background/introducing-flex/)
- [What development skills are needed?](https://www.sharetribe.com/docs/background/development-skills/)
- [Getting started with FTW](https://www.sharetribe.com/docs/tutorials/getting-started-with-ftw/)
tutorial.

## Requirements

Install required tools:
Expand Down Expand Up @@ -99,8 +110,9 @@ This command will create `.env` file and guide you trough setting up the require
variables. The `.env` file is the place to add your local configuration. It is ignored in Git, so
you'll have to add the corresponding configuration also to your server environment.

There are some mandatory configuration variables that are defined in the template. See the
[Environment configuration variables](env.md) documentation for more information.
There are some mandatory configuration variables that are defined in the template. See the Flex Docs
[FTW Environment configuration variables](https://www.sharetribe.com/docs/references/ftw-env/)
reference for more information.

See also the [src/config.js](../src/config.js) file for more configuration options.

Expand Down
7 changes: 4 additions & 3 deletions docs/deploying-to-production.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,12 @@ To deploy the application add at least the following variables:
| `PORT` | Must be set if the production environment doesn't set it by default. Not needed in Heroku. |
| `REACT_APP_SHARETRIBE_SDK_CLIENT_ID` | Client ID (API key) you can check from [Flex Console](https://flex-console.sharetribe.com/login/). You will get this from the Sharetribe team. |
| `REACT_APP_STRIPE_PUBLISHABLE_KEY` | Stripe publishable API key for generating tokens with Stripe API. It can be found from Stripe [API keys](https://dashboard.stripe.com/account/apikeys) page. Make sure to toggle _"View test data"_ on if you don't want to use real money yet. The secret key needs to be added to Flex Console. |
| `REACT_APP_MAPBOX_ACCESS_TOKEN` | Sign up for Mapbox and go to [account page](https://www.mapbox.com/account/access-tokens). Then click `Create access token`. For more information see the [Integrating to map providers](./map-providers.md) documentation. |
| `REACT_APP_MAPBOX_ACCESS_TOKEN` | Sign up for Mapbox and go to [account page](https://www.mapbox.com/account/access-tokens). Then click `Create access token`. See the Flex Docs [How to set up Mapbox for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-mapbox-for-ftw/) guide for more information. |
| `REACT_APP_CANONICAL_ROOT_URL` | Canonical root URL of the marketplace. E.g. https://the-name-of-your-app.herokuapp.com or your actual domain. This is needed for social media sharing and SEO optimization. |

There are also some other variables that can be used. See the
[Enviroment configuration variables](./env.md) documentation for more information.
There are also some other variables that can be used. See the Flex Docs
[FTW Environment configuration variables](https://www.sharetribe.com/docs/references/ftw-env/)
reference for more information.

### Building the app

Expand Down
41 changes: 2 additions & 39 deletions docs/env.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,42 +1,5 @@
# Environment configuration variables

The following configuration variables can be set to control the Flex template app behaviour. Most of
them have defaults that work for development environment. For production deploys most should be set.
Documentation moved to the Flex Docs site:

| Variable | Description |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| REACT_APP_MAPBOX_ACCESS_TOKEN | See: [Integrating to map providers](./map-providers.md) |
| REACT_APP_GOOGLE_MAPS_API_KEY | See: [Google Maps API key](./google-maps.md) (Alternative map provider) |
| REACT_APP_SHARETRIBE_SDK_CLIENT_ID | Client ID (API key). You can get this from the Flex Console. |
| REACT_APP_STRIPE_PUBLISHABLE_KEY | Stripe publishable API key for generating tokens with Stripe API. Use test key (prefix `pk_test_`) for development. The secret key needs to be added to Flex Console. |
| REACT_APP_SHARETRIBE_MARKETPLACE_CURRENCY | The currency used in the Marketplace as ISO 4217 currency code. For example: USD, EUR, CAD, AUD, etc. |
| REACT_APP_CANONICAL_ROOT_URL | Canonical root url of the marketplace. Needed for social media sharing and SEO optimization. |
| NODE_ENV | Node env. Use 'development' for development and 'production' for production. |
| PORT | Port for server to accept connections. |
| REACT_APP_ENV | A more fine grained env definition than NODE_ENV. Is used for example to differentiate envs in logging. |
| REACT_APP_SHARETRIBE_USING_SSL | Redirect HTTP to HTTPS? |
| SERVER_SHARETRIBE_TRUST_PROXY | Set when running the app behind a reverse proxy, e.g. in Heroku. |
| REACT_APP_SENTRY_DSN | See: [Error logging with Sentry](./sentry.md) |
| REACT_APP_CSP | See: [Content Security Policy (CSP)](./content-security-policy.md) |
| BASIC_AUTH_USERNAME | Set to enable HTTP Basic Auth |
| BASIC_AUTH_PASSWORD | Set to enable HTTP Basic Auth |
| REACT_APP_GOOGLE_ANALYTICS_ID | See: [Google Analytics](./analytics.md) |
| REACT_APP_AVAILABILITY_ENABLED | Enables availability calendar for listings. |
| REACT_APP_DEFAULT_SEARCHES_ENABLED | Enables default search suggestions in location autocomplete search input. |
| REACT_APP_SHARETRIBE_SDK_BASE_URL | The base url to access the Sharetribe Flex Marketplace API. FTW uses the correct one by default so no need to set this. |

## Defining configuration

When the app is started locally with `yarn run dev` or `yarn run dev-server`, you can set
environment variables by using the (gitignored) `.env` file. You can edit the basic variables via
`yarn run config` or by editing directly the .env file. Some variables can be edited only in the
.env file. The repository contains a template file `.env-template` with default configuration.

In production, it's recommended that you set the configuration via env variables and do not deploy
an .env file. The client application will only be packaged with env variables that start with
REACT_APP. This way server secrets don't end up in client bundles.

**With deploys note that the configuration options are bundled in the client package at build
time.** The configuration of the build environment must match run environment for things to work
consistently. To apply changes to configuration values client bundle must be rebuilt. Just
restarting the server is not enough.
https://www.sharetribe.com/docs/references/ftw-env/
Loading