Refresh README.md (#2768)
* Update README.md * Update README.md * Update README.md * docs: 📝 add articles to docs folder * docs: 📝 add configuration article * docs: 📝 add emojis 😋 * docs: 📝 restructure readme * docs: 📝 add deployment article * Empty-Commit
This commit is contained in:
Adrian Pilarczyk
GitHub
parent
0741d3ca2c
commit
f8f945d1af
7 changed files with 154 additions and 158 deletions
189
README.md
189
README.md
|
|
@ -18,180 +18,53 @@
|
||||||
<a href="https://twitter.com/getsaleor">🐦 Twitter</a>
|
<a href="https://twitter.com/getsaleor">🐦 Twitter</a>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
## Demo
|
<div align="center">
|
||||||
|
<a href="https://demo.saleor.io/dashboard">▶️ Demo</a>
|
||||||
|
<span> • </span>
|
||||||
|
<a href="https://githubbox.com/saleor/saleor-dashboard">🔎 Explore Code</a>
|
||||||
|
</div>
|
||||||
|
|
||||||
See the [public demo](https://demo.saleor.io/dashboard/) of Saleor Dashboard!
|
## Prerequisites
|
||||||
|
|
||||||
Or launch the demo on a free Heroku instance.
|
|
||||||
|
|
||||||
[](https://heroku.com/deploy)
|
|
||||||
|
|
||||||
## Getting Started
|
|
||||||
|
|
||||||
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
|
|
||||||
|
|
||||||
### Prerequisites
|
|
||||||
|
|
||||||
- Node.js v18+
|
- Node.js v18+
|
||||||
- A running instance of [Saleor](https://github.com/saleor/saleor/).
|
- A running instance of [Saleor](https://github.com/saleor/saleor/)
|
||||||
|
|
||||||
### Installing
|
## Development
|
||||||
|
|
||||||
Clone the repository:
|
1. Clone the repository:
|
||||||
|
|
||||||
```
|
```bash
|
||||||
$ git clone https://github.com/saleor/saleor-dashboard.git
|
git clone https://github.com/saleor/saleor-dashboard.git
|
||||||
```
|
```
|
||||||
|
|
||||||
Enter the project directory:
|
2. Enter the project directory:
|
||||||
|
|
||||||
```
|
```bash
|
||||||
$ cd saleor-dashboard
|
cd saleor-dashboard
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Using stable release
|
3. Install the dependencies:
|
||||||
|
|
||||||
Check [release log](https://github.com/saleor/saleor-dashboard/releases/) for the latest release
|
```bash
|
||||||
|
npm i
|
||||||
#### Using development version
|
|
||||||
|
|
||||||
If you want to use the latest development version, checkout to the `main` branch:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ git checkout main
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Install NPM dependencies:
|
4. Configure the env vars as described in [docs/configuration.md](docs/configuration.md).
|
||||||
|
|
||||||
```
|
5. Start the development server with:
|
||||||
$ npm i
|
|
||||||
|
```bash
|
||||||
|
npm run dev
|
||||||
```
|
```
|
||||||
|
|
||||||
### Configuration
|
> Note:
|
||||||
|
> If you see CORS errors, check [CORS configuration](https://docs.saleor.io/docs/3.x/developer/running-saleor/configuration#allowed_client_hosts) of your Saleor instance or CORS settings in the Cloud Console.
|
||||||
|
|
||||||
Create `.env` file in a root directory or set environment variables with following values:
|
## Docs
|
||||||
|
|
||||||
- `API_URI` (required) - URI of a running instance of Saleor GraphQL API.
|
- [Configuration ⚙️](docs/configuration.md)
|
||||||
If you are running Saleor locally with the default settings, set `API_URI` to: `http://localhost:8000/graphql/`.
|
- [Error tracking ⚠️](docs/error-tracking.md)
|
||||||
Make sure that you have `/` at the end of `API_URI`.
|
- [Running tests 🏁](docs/running-tests.md)
|
||||||
|
- [Usage with Docker 🐳](docs/docker.md)
|
||||||
- `APP_MOUNT_URI` - URI at which the Dashboard app will be mounted.
|
- [Sentry adapter 🗼](docs/sentry-adapter.md)
|
||||||
E.g. if you set `APP_MOUNT_URI` to `/dashboard/`, your app will be mounted at `http://localhost:9000/dashboard/`.
|
- [Deployment 🌐](docs/deployment.md)
|
||||||
|
|
||||||
- `STATIC_URL` - URL where the static files are located.
|
|
||||||
E.g. if you use S3 bucket, you should set it to the bucket's URL. By default Saleor assumes you serve static files from the root of your site at `http://localhost:9000/`.
|
|
||||||
|
|
||||||
- `MARKETPLACE_URL` - URL where Marketplace App can is located, if not found, will not render navigation link to Marketplace
|
|
||||||
|
|
||||||
- `SALEOR_APPS_PAGE_PATH` - Path joined to `MARKETPLACE_URL` to render Saleor Apps page
|
|
||||||
|
|
||||||
- `SALEOR_APPS_JSON_PATH` - Path joined to `MARKETPLACE_URL` to fetch list of Saleor Apps as JSON
|
|
||||||
|
|
||||||
- `APP_TEMPLATE_GALLERY_PATH` - Path joined to `MARKETPLACE_URL` to render App Template Gallery page
|
|
||||||
|
|
||||||
### Development
|
|
||||||
|
|
||||||
To start the development server run:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ npm run dev
|
|
||||||
```
|
|
||||||
|
|
||||||
In case you see CORS errors make sure to check [CORS configuration](https://docs.saleor.io/docs/3.x/developer/running-saleor/configuration#allowed_client_hosts) of your Saleor instance or CORS settings in the Cloud Console.
|
|
||||||
|
|
||||||
### Production
|
|
||||||
|
|
||||||
To build the application bundle run:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
### Error Tracking
|
|
||||||
|
|
||||||
Saleor Dashboard is using a generic error tracking wrapper function that takes care of the most popular use cases:
|
|
||||||
|
|
||||||
- initializing the tracker
|
|
||||||
- capturing exceptions and (optionally) displaying the event id
|
|
||||||
- setting basic user data (this is opt-in and disabled by default)
|
|
||||||
|
|
||||||
By default it ships with a Sentry adapter but any kind of error tracking software can be used by creating a custom adapter (using Sentry and TS types as an example).
|
|
||||||
|
|
||||||
Example:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
// src/services/errorTracking/index.ts
|
|
||||||
|
|
||||||
import { CustomAdapter } from "./adapters/";
|
|
||||||
|
|
||||||
const errorTracker = ErrorTrackerFactory(CustomAdapter(config));
|
|
||||||
```
|
|
||||||
|
|
||||||
### Running e2e tests
|
|
||||||
|
|
||||||
Add Cypress specific env variables to `.env` file (created in configuration section above):
|
|
||||||
|
|
||||||
```
|
|
||||||
CYPRESS_USER_NAME=
|
|
||||||
CYPRESS_USER_PASSWORD=
|
|
||||||
CYPRESS_SECOND_USER_NAME=
|
|
||||||
CYPRESS_PERMISSIONS_USERS_PASSWORD=
|
|
||||||
|
|
||||||
CYPRESS_mailHogUrl=
|
|
||||||
STRIPE_SECRET_KEY=
|
|
||||||
STRIPE_PUBLIC_KEY=
|
|
||||||
|
|
||||||
// not required
|
|
||||||
CYPRESS_RECORD_KEY= // if you want your local runs recorded
|
|
||||||
```
|
|
||||||
|
|
||||||
For values of those variables refer to our internal documentation.
|
|
||||||
|
|
||||||
You are ready to run cypress commands like:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
npm run cy:open
|
|
||||||
```
|
|
||||||
|
|
||||||
### Usage with docker
|
|
||||||
|
|
||||||
Build docker image:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
docker build --tag saleor-dashboard .
|
|
||||||
```
|
|
||||||
|
|
||||||
Run nginx from docker and bind it to port on your machine (in this example 8080):
|
|
||||||
|
|
||||||
```shell
|
|
||||||
docker run --publish 8080:80 --env "API_URL=<YOUR_API_URL>" saleor-dashboard
|
|
||||||
```
|
|
||||||
|
|
||||||
Enter `http://localhost:8080/` to use dashboard.
|
|
||||||
|
|
||||||
If you want to dynamically change `API_URL` in runtime you can use (assuming you have running container named `saleor-dashboard`):
|
|
||||||
|
|
||||||
```shell
|
|
||||||
docker exec -it -e API_URL=NEW_URL saleor-dashboard /docker-entrypoint.d/50-replace-api-url.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
### Usage with Sentry adapter
|
|
||||||
|
|
||||||
Sentry is used as the default tracker so no changes in code are necessary and the configuration is done via environment variables.
|
|
||||||
|
|
||||||
The following environment variables are available:
|
|
||||||
|
|
||||||
```
|
|
||||||
# Required
|
|
||||||
SENTRY_DSN=
|
|
||||||
|
|
||||||
# Optional
|
|
||||||
# https://docs.sentry.io/product/cli/configuration/
|
|
||||||
SENTRY_AUTH_TOKEN=
|
|
||||||
SENTRY_ORG=
|
|
||||||
SENTRY_PROJECT=
|
|
||||||
SENTRY_URL_PREFIX=
|
|
||||||
ENVIRONMENT=
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Crafted with ❤️ by [Saleor Commerce](https://saleor.io)
|
|
||||||
|
|
|
||||||
21
docs/configuration.md
Normal file
21
docs/configuration.md
Normal file
|
|
@ -0,0 +1,21 @@
|
||||||
|
# Configuration
|
||||||
|
|
||||||
|
Create `.env` file in a root directory or set environment variables with the following values:
|
||||||
|
|
||||||
|
- `API_URI` (required) - URI of Saleor GraphQL API instance.
|
||||||
|
If you are running Saleor locally with the default settings, set `API_URI` to: "http://localhost:8000/graphql/".
|
||||||
|
Make sure you have "/" at the end of `API_URI`.
|
||||||
|
|
||||||
|
- `APP_MOUNT_URI` - URI at which the Dashboard app will be mounted.
|
||||||
|
E.g., if you set `APP_MOUNT_URI` to "/dashboard/", your app will be mounted at "http://localhost:9000/dashboard/".
|
||||||
|
|
||||||
|
- `STATIC_URL` - URL where the static files are located.
|
||||||
|
E.g., if you use an S3 bucket, you should set it to the bucket's URL. By default, Saleor assumes you serve static files from the root of your site at "http://localhost:9000/".
|
||||||
|
|
||||||
|
- `MARKETPLACE_URL` - URL where Marketplace App is located. If not found, it will not render a navigation link to the Marketplace.
|
||||||
|
|
||||||
|
- `SALEOR_APPS_PAGE_PATH` - Path appended to `MARKETPLACE_URL` to render Saleor Apps page.
|
||||||
|
|
||||||
|
- `SALEOR_APPS_JSON_PATH` - Path appended to `MARKETPLACE_URL` to fetch a list of Saleor Apps as JSON.
|
||||||
|
|
||||||
|
- `APP_TEMPLATE_GALLERY_PATH` - Path appended to `MARKETPLACE_URL` to render App Template Gallery page.
|
||||||
19
docs/deployment.md
Normal file
19
docs/deployment.md
Normal file
|
|
@ -0,0 +1,19 @@
|
||||||
|
# Deployment
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
`saleor-dashboard` is a single-page application that the build process turns into a set of static files. You can deploy them anywhere (e.g. [Vercel](https://www.vercel.com/), [Netlify](https://www.netlify.com/)).
|
||||||
|
|
||||||
|
## Build
|
||||||
|
|
||||||
|
To build your `saleor-dashboard` instance, please run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
If you want to preview your build, you can do it with:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run preview
|
||||||
|
```
|
||||||
21
docs/docker.md
Normal file
21
docs/docker.md
Normal file
|
|
@ -0,0 +1,21 @@
|
||||||
|
# Usage with Docker
|
||||||
|
|
||||||
|
Build Docker image:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
docker build --tag saleor-dashboard .
|
||||||
|
```
|
||||||
|
|
||||||
|
Run nginx from Docker and bind it to port on your machine (in this example, it is "8080"):
|
||||||
|
|
||||||
|
```shell
|
||||||
|
docker run --publish 8080:80 --env "API_URL=<YOUR_API_URL>" saleor-dashboard
|
||||||
|
```
|
||||||
|
|
||||||
|
Enter `http://localhost:8080/` to use the dashboard.
|
||||||
|
|
||||||
|
If you want to change `API_URL` in runtime, you can use (assuming you have a running container named `saleor-dashboard`):
|
||||||
|
|
||||||
|
```shell
|
||||||
|
docker exec -it -e API_URL=NEW_URL saleor-dashboard /docker-entrypoint.d/50-replace-api-url.sh
|
||||||
|
```
|
||||||
19
docs/error-tracking.md
Normal file
19
docs/error-tracking.md
Normal file
|
|
@ -0,0 +1,19 @@
|
||||||
|
# Error Tracking
|
||||||
|
|
||||||
|
Saleor Dashboard uses a generic error-tracking wrapper function that takes care of the most popular use cases:
|
||||||
|
|
||||||
|
- initializing the tracker
|
||||||
|
- capturing exceptions and (optionally) displaying the event id
|
||||||
|
- setting basic user data (this is opt-in and disabled by default)
|
||||||
|
|
||||||
|
By default, it ships with a Sentry adapter, but you can use any error-tracking software by creating a custom adapter (using Sentry and TS types as an example).
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// src/services/errorTracking/index.ts
|
||||||
|
|
||||||
|
import { CustomAdapter } from "./adapters/";
|
||||||
|
|
||||||
|
const errorTracker = ErrorTrackerFactory(CustomAdapter(config));
|
||||||
|
```
|
||||||
25
docs/running-tests.md
Normal file
25
docs/running-tests.md
Normal file
|
|
@ -0,0 +1,25 @@
|
||||||
|
# Running E2E tests
|
||||||
|
|
||||||
|
Add Cypress-specific env variables to `.env` file (created in the configuration section above):
|
||||||
|
|
||||||
|
```
|
||||||
|
CYPRESS_USER_NAME=
|
||||||
|
CYPRESS_USER_PASSWORD=
|
||||||
|
CYPRESS_SECOND_USER_NAME=
|
||||||
|
CYPRESS_PERMISSIONS_USERS_PASSWORD=
|
||||||
|
|
||||||
|
CYPRESS_mailHogUrl=
|
||||||
|
STRIPE_SECRET_KEY=
|
||||||
|
STRIPE_PUBLIC_KEY=
|
||||||
|
|
||||||
|
// not required
|
||||||
|
CYPRESS_RECORD_KEY= // if you want your local runs recorded
|
||||||
|
```
|
||||||
|
|
||||||
|
For values of those variables, refer to our internal documentation.
|
||||||
|
|
||||||
|
You are ready to run Cypress commands like:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
npm run cy:open
|
||||||
|
```
|
||||||
18
docs/sentry-adapter.md
Normal file
18
docs/sentry-adapter.md
Normal file
|
|
@ -0,0 +1,18 @@
|
||||||
|
# Sentry adapter
|
||||||
|
|
||||||
|
We use Sentry as the default tracker. No changes in code are required for it to work. You can configure it with the environment variables.
|
||||||
|
|
||||||
|
The following environment variables are available:
|
||||||
|
|
||||||
|
```
|
||||||
|
# Required
|
||||||
|
SENTRY_DSN=
|
||||||
|
|
||||||
|
# Optional
|
||||||
|
# https://docs.sentry.io/product/cli/configuration/
|
||||||
|
SENTRY_AUTH_TOKEN=
|
||||||
|
SENTRY_ORG=
|
||||||
|
SENTRY_PROJECT=
|
||||||
|
SENTRY_URL_PREFIX=
|
||||||
|
ENVIRONMENT=
|
||||||
|
```
|
||||||
Loading…
Reference in a new issue