From 6dcd24ec8d5323374c60ac565ff19692d6b585bc Mon Sep 17 00:00:00 2001 From: hiluluke Date: Thu, 30 Aug 2018 21:41:19 +0800 Subject: [PATCH 1/6] Add docker related file to basic example --- examples/basics/Dockerfile | 10 +++++++ examples/basics/docker-compose.yml | 18 +++++++++++++ examples/basics/dockerignore | 2 ++ lib/copy-examples.js | 43 +++++++++++++++++++++--------- 4 files changed, 60 insertions(+), 13 deletions(-) create mode 100644 examples/basics/Dockerfile create mode 100644 examples/basics/docker-compose.yml create mode 100644 examples/basics/dockerignore diff --git a/examples/basics/Dockerfile b/examples/basics/Dockerfile new file mode 100644 index 000000000000..d369844d5bdf --- /dev/null +++ b/examples/basics/Dockerfile @@ -0,0 +1,10 @@ +FROM node:8.11.4 + +WORKDIR /app/website + +EXPOSE 3000 35729 +COPY ./docs /app/docs +COPY ./website /app/website +RUN yarn install + +CMD ["yarn", "start"] diff --git a/examples/basics/docker-compose.yml b/examples/basics/docker-compose.yml new file mode 100644 index 000000000000..6711192ae1e7 --- /dev/null +++ b/examples/basics/docker-compose.yml @@ -0,0 +1,18 @@ +version: "3" + +services: + docusaurus: + build: . + ports: + - 3000:3000 + - 35729:35729 + volumes: + - ./docs:/app/docs + - ./website/blog:/app/website/blog + - ./website/core:/app/website/core + - ./website/i18n:/app/website/i18n + - ./website/pages:/app/website/pages + - ./website/static:/app/website/static + - ./website/sidebars.json:/app/website/sidebars.json + - ./website/siteConfig.js:/app/website/siteConfig.js + working_dir: /app/website diff --git a/examples/basics/dockerignore b/examples/basics/dockerignore new file mode 100644 index 000000000000..27d2dae2b493 --- /dev/null +++ b/examples/basics/dockerignore @@ -0,0 +1,2 @@ +*/node_modules +*.log diff --git a/lib/copy-examples.js b/lib/copy-examples.js index 1247b2c643f4..49381eec55a9 100755 --- a/lib/copy-examples.js +++ b/lib/copy-examples.js @@ -155,20 +155,34 @@ if (feature === 'translations') { exampleSiteCreated = true; blogCreated = true; } - // copy .gitignore file - let gitignoreName = '.gitignore'; - if (fs.existsSync(`${CWD}/../.gitignore`)) { - gitignoreName = '.gitignore-example-from-docusaurus'; - console.log( - `${chalk.yellow('.gitignore already exists')} in ${chalk.yellow( - CWD - )}. Creating an example gitignore file for you to copy from if desired.\n` + + const copyFileOutWebsiteFolder = (fileNameFrom, isHide) => { + let fileNameTo = isHide ? `.${fileNameFrom}` : fileNameFrom; + if (fs.existsSync(`${CWD}/../${fileNameTo}`)) { + fileNameTo = `${fileNameTo}-example-from-docusaurus`; + console.log( + `${chalk.yellow(fileNameTo + ' already exists')} in ${chalk.yellow( + CWD + )}. Creating an example ${fileNameTo} file for you to copy from if desired.\n` + ); + } + fs.copySync( + path.join(folder, fileNameFrom), + path.join(CWD, `/../${fileNameTo}`) ); - } - fs.copySync( - path.join(folder, 'gitignore'), - path.join(CWD, `/../${gitignoreName}`) - ); + }; + + // copy .gitignore file + copyFileOutWebsiteFolder('gitignore', true); + + // copy Dockerfile file + copyFileOutWebsiteFolder('Dockerfile', false); + + // copy docker-compose.yml file + copyFileOutWebsiteFolder('docker-compose.yml', false); + + // copy .dockerignore file + copyFileOutWebsiteFolder('dockerignore', true); // copy other files const files = glob.sync(`${folder}/**/*`); @@ -179,6 +193,9 @@ if (feature === 'translations') { const containingFolder = path.basename(path.dirname(file)); if ( path.basename(file) === 'gitignore' || + path.basename(file) === 'Dockerfile' || + path.basename(file) === 'docker-compose.yml' || + path.basename(file) === 'dockerignore' || containingFolder === 'blog-examples-from-docusaurus' || containingFolder === 'docs-examples-from-docusaurus' ) { From a1a26d1c2e53b2b966c9dfb95ecdc87c220bccee Mon Sep 17 00:00:00 2001 From: hiluluke Date: Sat, 1 Sep 2018 17:06:56 +0800 Subject: [PATCH 2/6] Add docker support document --- docs/getting-started-docker.md | 63 ++++++++++++++++++++++++++++++++++ website/sidebars.json | 3 +- 2 files changed, 65 insertions(+), 1 deletion(-) create mode 100644 docs/getting-started-docker.md diff --git a/docs/getting-started-docker.md b/docs/getting-started-docker.md new file mode 100644 index 000000000000..b31feee551a2 --- /dev/null +++ b/docs/getting-started-docker.md @@ -0,0 +1,63 @@ +--- +id: docker +title: Docker +--- + +[Docker](https://www.docker.com/) is a tool that enables you to create, deploy, and manage lightweight, stand-alone packages that contain everything needed to run an application. It can help us to avoid conflicting dependencies when we edit the doc and publish gh-pages. + +## Run the local webserver in docker + +You need to ensure you have install [docker](https://www.docker.com/get-started) and install docusaurus correctly. + +To run the local webserver you only need to do a few step: + +1. Enter the folder where you have install docusaurus, and then run `docker build -t docusaurus-doc .` + + After the build phase finished, you can run `docker images` to check the docker image list. + + > We have already added a `Dockerfile` in your project when you install docusaurus, So you can build it directly. + +2. Run docker start command: `docker run --rm -p 3000:3000 docusaurus-doc` + + It will run a container with the image `docusaurus-doc`.And you can run `docker ps` to see the container info. + +## Use docker-compose + +We can use docker-compose to configure our application, run it with a single command. + +> Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration. + +Using Compose is basically a three-step process: + +1. Define your app’s environment with a Dockerfile so it can be reproduced anywhere. + +2. Define the services that make up your app in docker-compose.yml so they can be run together in an isolated environment. + +3. Run docker-compose up and Compose starts and runs your entire app. + +We have already added a basic `docker-compose.yml` in your project: +``` yml +version: "3" + +services: + docusaurus: + build: . + ports: + - 3000:3000 + - 35729:35729 + volumes: + - ./docs:/app/docs + - ./website/blog:/app/website/blog + - ./website/core:/app/website/core + - ./website/i18n:/app/website/i18n + - ./website/pages:/app/website/pages + - ./website/static:/app/website/static + - ./website/sidebars.json:/app/website/sidebars.json + - ./website/siteConfig.js:/app/website/siteConfig.js + working_dir: /app/website + +``` + +To run a local webserver with `docker-compose` you only need to run `docker-compose up`. + +If you want to build static HTML pages and publish, you can run `docker-compose run docusaurus bash -c 'yarn publish-gh-pages'` diff --git a/website/sidebars.json b/website/sidebars.json index 2542af519de5..a32af74fe10c 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -4,7 +4,8 @@ "installation", "site-preparation", "site-creation", - "publishing" + "publishing", + "docker" ], "Guides": [ "adding-blog", From 87bd1bea05adb0f9490e600e6d58d9a819f892c8 Mon Sep 17 00:00:00 2001 From: endiliey Date: Thu, 6 Sep 2018 01:51:33 +0800 Subject: [PATCH 3/6] nits & better console.log --- lib/copy-examples.js | 55 ++++++++++++++++++--------------------- lib/write-translations.js | 9 ++++--- 2 files changed, 31 insertions(+), 33 deletions(-) diff --git a/lib/copy-examples.js b/lib/copy-examples.js index 49381eec55a9..c75e5abe8ba3 100755 --- a/lib/copy-examples.js +++ b/lib/copy-examples.js @@ -124,11 +124,9 @@ if (feature === 'translations') { // copy docs examples if (fs.existsSync(`${CWD}/../docs-examples-from-docusaurus`)) { console.log( - `${chalk.yellow( - 'Example docs already exist!' - )} Rename or remove ${chalk.yellow( - `${outerFolder}/docs-examples-from-docusaurus` - )} to regenerate example docs.\n` + `- ${chalk.green( + 'docs-examples-from-docusaurus' + )} already exists in ${chalk.blue(outerFolder)}.` ); } else { fs.copySync( @@ -141,11 +139,9 @@ if (feature === 'translations') { // copy blog examples if (fs.existsSync(`${CWD}/blog-examples-from-docusaurus`)) { console.log( - `${chalk.yellow( - 'Example blog posts already exist!' - )} Rename or remove ${chalk.yellow( - `${outerFolder}/website/blog-examples-from-docusaurus` - )} to regenerate example blog posts.\n` + `- ${chalk.green( + 'blog-examples-from-docusaurus' + )} already exists in ${chalk.blue(`${outerFolder}/website`)}.` ); } else { fs.copySync( @@ -156,33 +152,32 @@ if (feature === 'translations') { blogCreated = true; } - const copyFileOutWebsiteFolder = (fileNameFrom, isHide) => { - let fileNameTo = isHide ? `.${fileNameFrom}` : fileNameFrom; - if (fs.existsSync(`${CWD}/../${fileNameTo}`)) { - fileNameTo = `${fileNameTo}-example-from-docusaurus`; + const copyFileToWebsite = (fileNameFrom, fileNameTo) => { + const copiedFileName = fileNameTo || fileNameFrom; + const src = path.join(folder, fileNameFrom); + const dest = path.join(CWD, '..', copiedFileName); + if (fs.existsSync(dest)) { console.log( - `${chalk.yellow(fileNameTo + ' already exists')} in ${chalk.yellow( - CWD - )}. Creating an example ${fileNameTo} file for you to copy from if desired.\n` + `- ${chalk.green(copiedFileName)} already exists in ${chalk.blue( + outerFolder + )}.` ); + } else { + fs.copySync(src, dest); } - fs.copySync( - path.join(folder, fileNameFrom), - path.join(CWD, `/../${fileNameTo}`) - ); }; // copy .gitignore file - copyFileOutWebsiteFolder('gitignore', true); + copyFileToWebsite('gitignore', '.gitignore'); // copy Dockerfile file - copyFileOutWebsiteFolder('Dockerfile', false); + copyFileToWebsite('Dockerfile'); // copy docker-compose.yml file - copyFileOutWebsiteFolder('docker-compose.yml', false); + copyFileToWebsite('docker-compose.yml'); // copy .dockerignore file - copyFileOutWebsiteFolder('dockerignore', true); + copyFileToWebsite('dockerignore', '.dockerignore'); // copy other files const files = glob.sync(`${folder}/**/*`); @@ -210,11 +205,11 @@ if (feature === 'translations') { exampleSiteCreated = true; } catch (e) { console.log( - `${chalk.yellow( - `${path.basename(filePath)} already exists` - )} in ${chalk.yellow( - `website${filePath.split(path.basename(filePath))[0]}` - )}. Rename or remove the file to regenerate an example version.\n` + `- ${chalk.green( + `${path.basename(filePath)}` + )} already exists in ${chalk.blue( + `${outerFolder}/website${filePath.split(path.basename(filePath))[0]}` + )}.` ); } }); diff --git a/lib/write-translations.js b/lib/write-translations.js index ce3f9aad8fbe..ef6ab435b76c 100755 --- a/lib/write-translations.js +++ b/lib/write-translations.js @@ -176,13 +176,16 @@ function execute() { // Manually add 'Help Translate' to en.json translations['pages-strings'][ 'Help Translate|recruit community translators for your project' - ] = 'Help Translate'; + ] = + 'Help Translate'; translations['pages-strings'][ 'Edit this Doc|recruitment message asking to edit the doc source' - ] = 'Edit'; + ] = + 'Edit'; translations['pages-strings'][ 'Translate this Doc|recruitment message asking to translate the docs' - ] = 'Translate'; + ] = + 'Translate'; translations['pages-strings'] = Object.assign( translations['pages-strings'], customTranslations['pages-strings'] From b00b933ab9bd04e9038fe12f519af9cacebf1e40 Mon Sep 17 00:00:00 2001 From: endiliey Date: Thu, 6 Sep 2018 01:56:19 +0800 Subject: [PATCH 4/6] docs nit --- docs/getting-started-docker.md | 4 ++-- lib/write-translations.js | 9 +++------ 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/getting-started-docker.md b/docs/getting-started-docker.md index b31feee551a2..d33643c4cbff 100644 --- a/docs/getting-started-docker.md +++ b/docs/getting-started-docker.md @@ -3,11 +3,11 @@ id: docker title: Docker --- -[Docker](https://www.docker.com/) is a tool that enables you to create, deploy, and manage lightweight, stand-alone packages that contain everything needed to run an application. It can help us to avoid conflicting dependencies when we edit the doc and publish gh-pages. +[Docker](https://www.docker.com/) is a tool that enables you to create, deploy, and manage lightweight, stand-alone packages that contain everything needed to run an application. It can help us to avoid conflicting dependencies & unwanted behavior when running Docusaurus. ## Run the local webserver in docker -You need to ensure you have install [docker](https://www.docker.com/get-started) and install docusaurus correctly. +You need to ensure you have installed [docker](https://www.docker.com/get-started). To run the local webserver you only need to do a few step: diff --git a/lib/write-translations.js b/lib/write-translations.js index ef6ab435b76c..ce3f9aad8fbe 100755 --- a/lib/write-translations.js +++ b/lib/write-translations.js @@ -176,16 +176,13 @@ function execute() { // Manually add 'Help Translate' to en.json translations['pages-strings'][ 'Help Translate|recruit community translators for your project' - ] = - 'Help Translate'; + ] = 'Help Translate'; translations['pages-strings'][ 'Edit this Doc|recruitment message asking to edit the doc source' - ] = - 'Edit'; + ] = 'Edit'; translations['pages-strings'][ 'Translate this Doc|recruitment message asking to translate the docs' - ] = - 'Translate'; + ] = 'Translate'; translations['pages-strings'] = Object.assign( translations['pages-strings'], customTranslations['pages-strings'] From 91763b0f769906e296d6dcbce0cca0f071a121cb Mon Sep 17 00:00:00 2001 From: endiliey Date: Thu, 6 Sep 2018 19:28:49 +0800 Subject: [PATCH 5/6] rename func copyFileToWebsite to copyFileToProjectFolder --- lib/copy-examples.js | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/lib/copy-examples.js b/lib/copy-examples.js index c75e5abe8ba3..c766676b7910 100755 --- a/lib/copy-examples.js +++ b/lib/copy-examples.js @@ -152,7 +152,7 @@ if (feature === 'translations') { blogCreated = true; } - const copyFileToWebsite = (fileNameFrom, fileNameTo) => { + const copyFileToProjectFolder = (fileNameFrom, fileNameTo) => { const copiedFileName = fileNameTo || fileNameFrom; const src = path.join(folder, fileNameFrom); const dest = path.join(CWD, '..', copiedFileName); @@ -168,16 +168,16 @@ if (feature === 'translations') { }; // copy .gitignore file - copyFileToWebsite('gitignore', '.gitignore'); + copyFileToProjectFolder('gitignore', '.gitignore'); // copy Dockerfile file - copyFileToWebsite('Dockerfile'); + copyFileToProjectFolder('Dockerfile'); // copy docker-compose.yml file - copyFileToWebsite('docker-compose.yml'); + copyFileToProjectFolder('docker-compose.yml'); // copy .dockerignore file - copyFileToWebsite('dockerignore', '.dockerignore'); + copyFileToProjectFolder('dockerignore', '.dockerignore'); // copy other files const files = glob.sync(`${folder}/**/*`); From 3094afdce3cc21a8ddf6bab0f4778a2c6b68e411 Mon Sep 17 00:00:00 2001 From: Eric Nakagawa Date: Thu, 6 Sep 2018 11:13:13 -0700 Subject: [PATCH 6/6] Rewrote some of the new Docker copy. --- docs/getting-started-docker.md | 36 +++++++++++++++++----------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/getting-started-docker.md b/docs/getting-started-docker.md index d33643c4cbff..3c6a8baa8b45 100644 --- a/docs/getting-started-docker.md +++ b/docs/getting-started-docker.md @@ -7,35 +7,35 @@ title: Docker ## Run the local webserver in docker -You need to ensure you have installed [docker](https://www.docker.com/get-started). +Ensure you have previously installed [docker](https://www.docker.com/get-started). -To run the local webserver you only need to do a few step: +To run the local webserver: -1. Enter the folder where you have install docusaurus, and then run `docker build -t docusaurus-doc .` - - After the build phase finished, you can run `docker images` to check the docker image list. - - > We have already added a `Dockerfile` in your project when you install docusaurus, So you can build it directly. +1. **Build the docker image** -- Enter the folder where you have Docusaurus installed. Run `docker build -t docusaurus-doc .` -2. Run docker start command: `docker run --rm -p 3000:3000 docusaurus-doc` + Once the build phase finishes, you can verify the image exists by running `docker images`. - It will run a container with the image `docusaurus-doc`.And you can run `docker ps` to see the container info. + > We now include a `Dockerfile` when you install Docusaurus. -## Use docker-compose +2. **Run the Docusaurus container** -- To start docker run `docker run --rm -p 3000:3000 docusaurus-doc` -We can use docker-compose to configure our application, run it with a single command. + This will start a docker container with the image `docusaurus-doc`. To see more detailed container info run `docker ps` . -> Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration. +## Use docker-compose -Using Compose is basically a three-step process: +We can also use `docker-compose` to configure our application. This feature of docker allows you to run the webserver and any additional services with a single command. + +> Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration. + +Using Compose is a three-step process: 1. Define your app’s environment with a Dockerfile so it can be reproduced anywhere. -2. Define the services that make up your app in docker-compose.yml so they can be run together in an isolated environment. +2. Define the services that make up your app in `docker-compose.yml` so they can be run together in an isolated environment. -3. Run docker-compose up and Compose starts and runs your entire app. +3. Run `docker-compose up` and Compose starts and runs your entire app. -We have already added a basic `docker-compose.yml` in your project: +We include a basic `docker-compose.yml` in your project: ``` yml version: "3" @@ -58,6 +58,6 @@ services: ``` -To run a local webserver with `docker-compose` you only need to run `docker-compose up`. +To run a local webserver with `docker-compose` run `docker-compose up`. -If you want to build static HTML pages and publish, you can run `docker-compose run docusaurus bash -c 'yarn publish-gh-pages'` +To build static HTML pages for publishing run `docker-compose run docusaurus bash -c 'yarn publish-gh-pages'`