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

Fix text which should be bash in site/README.md #875

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Fix text which should be bash in site/README.md #875

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
99 changes: 46 additions & 53 deletions site/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,32 +2,30 @@

A site for hosting codelabs content.


## Prerequisites

The project requires the following major dependencies:

- [Go](https://golang.org/dl/) language
- [Node.js](https://nodejs.org/en/download/) v10+ and [npm](https://www.npmjs.com/get-npm)
- [gsutil](https://cloud.google.com/storage/docs/gsutil_install)
- [claat](https://github.com/googlecodelabs/tools/tree/master/claat#install)
- [claat](https://github.com/googlecodelabs/tools/tree/main/claat#install)

With Node installed, run `npm install` in the root of the `site` (this folder):

```text
$ npm install
```bash
npm install
```

(Optional) npm installs binstubs at `./node_modules/.bin/`. When running tasks
like `gulp`, you may want to add `./node_modules/.bin/` to your `$PATH` for convenience:

```text
$ export PATH="./node_modules/.bin/:$PATH"
```bash
export PATH="./node_modules/.bin/:$PATH"
```

This does pose a mild security risk, so please do so at your own risk.


## Development

### Serve
Expand All @@ -37,8 +35,8 @@ with the codelabs content as an argument. This will compile all the views and
codelabs into the `build/` directory and start a web server to serve that
content.

```text
$ gulp serve
```bash
gulp serve
```

The output will include the address where the server is running
Expand All @@ -48,8 +46,8 @@ You can also serve the completely compiled and minified (prod) version with the
`serve:dist` command. Always run this before publishing, as it will show you an
replica of what will appear on staging/production.

```text
$ gulp serve:dist
```bash
gulp serve:dist
```

### Views
Expand Down Expand Up @@ -161,27 +159,26 @@ Instead, build all views and then visit the appropriate URL. If you still wish
to build a single set of views, you can do so with the `--views-filter`
parameter:

```text
$ gulp serve --views-filter='^event-*'
```bash
gulp serve --views-filter='^event-*'
```

Note this filter takes a regular expression. By default, all views are built.


## Deployment

Once you build, serve, and verify your labs, you're on your own for publishing the artifacts. There are many ways to publish a static web site and we won't try to cover them all, however, we have included support for deploying your landing pages and codelabs to Google Cloud Storage (GCS).

### Setup for GCS Support

#### Set environment variables like this (use your own names):
#### Set environment variables like this (use your own names)

```
export STAGING_BUCKET=gs://mco-codelabs-staging
export PROD_BUCKET=gs://mco-codelabs-prod
```

#### Create staging and production buckets like this (use your own names):
#### Create staging and production buckets like this (use your own names)

```
18:42:32 site$ gsutil mb is $STAGING_BUCKET
Expand All @@ -195,9 +192,9 @@ Creating gs://mco-codelabs-prod/...
1. Make newly uploaded files world-readable and ensure user@ has owner
permissions:

```text
$ gsutil defacl ch -g all:R -u [email protected]:O $STAGING_BUCKET $PROD_BUCKET
$ gsutil iam ch allUsers:objectViewer $STAGING_BUCKET $PROD_BUCKET
```bash
gsutil defacl ch -g all:R -u [email protected]:O $STAGING_BUCKET $PROD_BUCKET
gsutil iam ch allUsers:objectViewer $STAGING_BUCKET $PROD_BUCKET
```

Add as many `-u user@` as you require. This ensures the users will remain
Expand All @@ -213,20 +210,20 @@ local copy), specify `--delete-missing` on the publish command.

1. Compile and minify the build:

```text
$ gulp dist
```bash
gulp dist
```

1. Deploy views to the staging bucket:

```text
$ gulp publish:staging:views --staging-bucket=$STAGING_BUCKET
```bash
gulp publish:staging:views --staging-bucket=$STAGING_BUCKET
```

1. Deploy codelabs to the staging bucket:

```text
$ gulp publish:staging:codelabs --staging-bucket=$STAGING_BUCKET
```bash
gulp publish:staging:codelabs --staging-bucket=$STAGING_BUCKET
```

1. Visit the [staging site](https://mco-codelabs-staging.storage.googleapis.com/index.html) (modify link to match your staging bucket name).
Expand All @@ -246,14 +243,14 @@ specify `--delete-missing` on the publish command.

1. Deploy views from the staging bucket to the production bucket:

```text
$ gulp publish:prod:views --staging-bucket=$STAGING_BUCKET --prod-bucket=$PROD_BUCKET
```bash
gulp publish:prod:views --staging-bucket=$STAGING_BUCKET --prod-bucket=$PROD_BUCKET
```

1. Deploy codelabs from the staging bucket to the production bucket:

```text
$ gulp publish:prod:codelabs --staging-bucket=$STAGING_BUCKET --prod-bucket=$PROD_BUCKET
```bash
gulp publish:prod:codelabs --staging-bucket=$STAGING_BUCKET --prod-bucket=$PROD_BUCKET
```

1. Visit the [production site](https://mco-codelabs-prod.storage.googleapis.com/index.html) (modify link to match your production bucket name).
Expand All @@ -269,51 +266,49 @@ to use GCS directly for serving, the bucket name **must** be a valid domain.

1. Create a new bucket:

```text
$ gsutil mb gs://codelabs.mycompany.com
```bash
gsutil mb gs://codelabs.mycompany.com
```

1. Make newly uploaded files world-readable and ensure user@ has owner
permissions:

```text
$ gsutil defacl ch -g all:R -u [email protected]:O gs://codelabs.mycompany.com
$ gsutil iam ch allUsers:objectViewer gs://codelabs.mycompany.com
```bash
gsutil defacl ch -g all:R -u [email protected]:O gs://codelabs.mycompany.com
gsutil iam ch allUsers:objectViewer gs://codelabs.mycompany.com
```

Add as many `-u user@` as you require. This ensures the users will remain
owners no matter who updates your bucket.

1. Set the default main page suffix and not found page:

```text
$ gsutil web set -m index.html -e 404.html gs://codelabs.mycompany.com
```bash
gsutil web set -m index.html -e 404.html gs://codelabs.mycompany.com
```

This option is only available on bucket names that are valid domains.


Follow the steps in [deploy to staging](#deploy-to-staging) with a custom
`--staging-bucket` parameter. See [#options](#options) for information.


### Deploy single view or codelab

Where possible, build and publish the entire website. This will ensure all
assets are up-to-date.

To build and publish a set of views to staging:

```text
$ gulp dist --views-filter=^my-event
$ gulp publish:staging:views
```bash
gulp dist --views-filter=^my-event
gulp publish:staging:views
```

To build and publish a set of codelabs to staging:

```text
$ gulp dist --codelabs-filter=^my-codelab
$ gulp publish:staging:codelabs
```bash
gulp dist --codelabs-filter=^my-codelab
gulp publish:staging:codelabs
```

## Options
Expand Down Expand Up @@ -359,27 +354,25 @@ is "html"
`--codelab-source` - Google Doc ID from which to build codelab. This can be
specified multiple times to build from multiple sources.


## Testing

To run the tests manually in a browser, execute the following:

```text
$ gulp serve
$ open http://localhost:8000/app/js/all_tests.html
```bash
gulp serve
open http://localhost:8000/app/js/all_tests.html
```


## Help

For help documentation/usage of the Gulp tasks, run:

```text
$ gulp -T
```bash
gulp -T
```

If gulp startup times are really slow, try removing `node_modules/` or running

```text
$ npm dedupe
```bash
npm dedupe
```