knight/datahub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #539 from datopian/ref/ReadMe

Browse Source 
Refactor/Update ReadMe
This commit is contained in:
Rufus Pollock
2021-04-19 11:24:27 +02:00
committed by GitHub
parent 883582d386 5983898e59
commit 3aa0928981
1 changed files with 52 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
scripts/README.md
View File

@@ -1,19 +1,27 @@
## Steps to use scripts # Deploying a single page dataset to Github pages
### Deploy Single dataset with github actions In the following sections, we show you how to deploy a single page, Frictionless dataset to Github pages. We show you three ways to do this as listed below:
The github actions below will automatically build and deploy a single dataset to gh-pages branch. Folow the steps below to achieve this: * Deploying datasets automatically by setting up a github actions script.
* Deploying datasets from a local bash script with portal code commits
* Deploying datasets from a local bash script without portal code commits
**Step 1:** In the dataset repository you want to deploy, create a github secret with the name `PORTAL_REPO_NAME` and the value should be the name of the repository. ## Deploying datasets automatically by setting up a github actions script.
The github actions below will automatically build and deploy a single page, Frictionless dataset to `gh-pages` branch. Folow the steps below to achieve this:
### Step 1
In the dataset repository you want to deploy, create a github secret with the name `PORTAL_REPO_NAME` and the value should be the name of the repository.
See steps on creating a secret [here](https://docs.github.com/en/actions/reference/encrypted-secrets) See steps on creating a secret [here](https://docs.github.com/en/actions/reference/encrypted-secrets)
<img src="./assets/secrets.png" /> <img src="./assets/secrets.png" />
**Step 2:** Clone/Pull the dataset repository you want deploy: ### Step 2
Clone/Pull the dataset repository you want deploy:
```bash ```bash
git clone https://github.com/datasets/finance-vix git clone https://github.com/datasets/finance-vix
``` ```
**Step 3:** Create a `.github/workflow` directory and add a `main.yml` file with the following content: ### Step 3
Create a `.github/workflow` directory and add a `main.yml` file with the following content:
```bash ```bash
name: github pages name: github pages
@@ -46,39 +54,45 @@ jobs:
``` ```
You can see/download the action file [here]("./actions/single-dataset-ssg.yml") You can see/download the action file [here]("./actions/single-dataset-ssg.yml")
**Step 3:** Commit and push your code: ### Step 3
Commit and push your code:
```bash ```bash
git add . git add .
git commit -m "Build dataset page" git commit -m "Build dataset page"
git push git push
``` ```
**Step 4:** ### Step 4
Wait for a while as your page builds, and once you see the green check mark, navigate to your repository's github `pages` in settings, set the `source` to `gh-pages` and folder to `/root`: Wait for a while as your page builds, and once you see the green check mark, navigate to your repository's github `pages` in settings, set the `source` to `gh-pages` and folder to `/root`:
<img src='./assets/sdnocommit.png' /> <img src='./assets/sdnocommit.png' />
**Step 5:** ### Step 5
Open your deployed site at `https://<your github username>/github.io/<dataset repo name>/index.html` Open your deployed site at `https://<your github username>/github.io/<dataset repo name>/index.html`
______ ______
### Deploy single dataset without commiting portaljs code
Users who want to deploy datasets from a local bash script
without saving/commiting the portal.js code, can use the script shown below.
## Other build options Using this script means you do not have access to the portal.js code used to generate the dataset page, and as such cannot modify/extend it.
### Deploy single dataset with no portal commit
This script creates and commit only the build files from nextjs to the gh-pages branch.
**Step 1:** Clone/Pull the dataset repository you want deploy. For example: This script creates and commit only the build/output files to the gh-pages branch. Follow the steps below to achieve this.
### Step 1
Clone/Pull the dataset repository you want deploy. For example:
```bash ```bash
git clone https://github.com/datasets/finance-vix git clone https://github.com/datasets/finance-vix
cd finance-vix cd finance-vix
``` ```
**Step 2:** In a terminal, export an env variable with the name of your dataset github repo. ### Step 2
In a terminal, export an env variable with the name of your dataset github repo.
For example if deploying https://github.com/datasets/finance-vix, then export the name as: For example if deploying https://github.com/datasets/finance-vix, then export the name as:
```bash ```bash
export PORTAL_REPO_NAME=finance-vix export PORTAL_REPO_NAME=finance-vix
``` ```
**Step 3:** In the dataset repository's root folder, create a file called `portal.sh` and paste the following content: ### Step 3
In the dataset repository's root folder, create a file called `portal.sh` and paste the following content:
```bash ```bash
#!/bin/bash #!/bin/bash
git checkout -b gh-pages git checkout -b gh-pages
@@ -108,45 +122,53 @@ git add $PWD'/_next' $PWD'/index.html' $PWD'/dataset' $PWD'/404.html' $PWD'/.noj
git commit -m "Build new dataset page" git commit -m "Build new dataset page"
git push origin gh-pages git push origin gh-pages
``` ```
**Step 4:** Run the bash script in a terminal with: ### Step 4
Run the bash script in a terminal with:
```bash ```bash
source portal.sh source portal.sh
``` ```
> Note: Use `source` instead of `bash` so that the script can work well with environment variables. > Note: Use `source` instead of `bash` so that the script can work well with environment variables.
**Step 5:** ### Step 5
Go to your repository's github `pages` in setting and set the Branch to gh-pages and folder to root: Go to your repository's github `pages` in setting and set the Branch to gh-pages and folder to root:
<img src='./assets/sdnocommit.png' /> <img src='./assets/sdnocommit.png' />
**Step 5:** ### Step 6
Open your deployed site at `https://<your github username>/github.io/<dataset repo name>` Open your deployed site at `https://<your github username>/github.io/<dataset repo name>`
____ ____
### Deploy single dataset with portal commit ## Deploy single dataset with portal commit
This script creates and commit the portal code and also adds an automated script to deploy to gh-page. Follow the steps below to use this script. Users who want access to the portal.js code used for generating the dataset page can use the script shown in the following section.
**Step 1:** Create a Github Personal Access Token (PAT). See steps [here](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) This script creates and commit the portal.js code to the root branch and also adds an automated script to deploy to gh-page. Follow the steps below to use this script.
**Step 2:** In the dataset repository you want to deploy, create a github secret with the name `PORTAL_NEXT_TOKEN`. The value should be the PAT created in step 1. See steps on creating a secret [here](https://docs.github.com/en/actions/reference/encrypted-secrets) ### Step 1
Create a Github Personal Access Token (PAT). See steps [here](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token)
### Step 2
In the dataset repository you want to deploy, create a github secret with the name `PORTAL_NEXT_TOKEN`. The value should be the PAT created in step 1. See steps on creating a secret [here](https://docs.github.com/en/actions/reference/encrypted-secrets)
> Note: Without the PAT and the secret configured, the automatic build will fail. > Note: Without the PAT and the secret configured, the automatic build will fail.
**Step 3:** Clone/Pull the dataset repository you want deploy. For example: ### Step 3
Clone/Pull the dataset repository you want deploy. For example:
```bash ```bash
git clone https://github.com/datasets/finance-vix git clone https://github.com/datasets/finance-vix
cd finance-vix cd finance-vix
``` ```
**Step 4:** In your computer's terminal/command prompt, export an environment variable with the name of your dataset's github repo. ### Step 4
In your computer's terminal/command prompt, export an environment variable with the name of your dataset's github repo.
For example if you want to deploy the dataset at https://github.com/datasets/finance-vix, then export the name using the command: For example if you want to deploy the dataset at https://github.com/datasets/finance-vix, then export the name using the command:
```bash ```bash
export PORTAL_REPO_NAME=finance-vix export PORTAL_REPO_NAME=finance-vix
``` ```
**Step 5:** Create a file called `portal.sh` and paste the following content: ### Step 5
Create a file called `portal.sh` and paste the following content:
```bash ```bash
#!/bin/bash #!/bin/bash
rm -rf portal rm -rf portal
@@ -175,17 +197,18 @@ git commit -m "Add dataset build feature"
git push git push
``` ```
**Step 6:** Run the bash script with: ### Step 6
Run the bash script with:
```bash ```bash
source portal.sh source portal.sh
``` ```
> Note: Use `source` instead of `bash` so that the script can work well with environment variables. > Note: Use `source` instead of `bash` so that the script can work well with environment variables.
**Step 7:** ### Step 7
Go to your repository's github `pages` in setting and set the Branch to gh-pages and folder to root: Go to your repository's github `pages` in setting and set the Branch to gh-pages and folder to root:
<img src='./assets/sdnocommit.png' /> <img src='./assets/sdnocommit.png' />
**Step 8:** ### Step 8
Open your deployed site at `https://<your github username>/github.io/<dataset repo name>` Open your deployed site at `https://<your github username>/github.io/<dataset repo name>`
____ ____