Merge pull request #936 from wszgxa/add-docker-support

Add docker support

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 & unwanted behavior when running Docusaurus.
+
+## Run the local webserver in docker
+
+Ensure you have previously installed [docker](https://www.docker.com/get-started).
+
+To run the local webserver:
+
+1. **Build the docker image** -- Enter the folder where you have Docusaurus installed. Run `docker build -t docusaurus-doc .`
+
+    Once the build phase finishes, you can verify the image exists by running `docker images`.
+
+    > We now include a `Dockerfile` when you install Docusaurus.
+
+2. **Run the Docusaurus container** -- To start docker run `docker run --rm -p 3000:3000 docusaurus-doc`
+
+    This will start a docker container with the image `docusaurus-doc`. To see more detailed container info run `docker ps` .
+
+## Use docker-compose
+
+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.
+
+3. Run `docker-compose up` and Compose starts and runs your entire app.
+
+We include 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` run `docker-compose up`.
+
+To build static HTML pages for publishing run `docker-compose run docusaurus bash -c 'yarn publish-gh-pages'`

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"]

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

examples/basics/dockerignore

@@ -0,0 +1,2 @@
+*/node_modules
+*.log

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(
+      `- ${chalk.green(
-        'Example docs already exist!'
+        'docs-examples-from-docusaurus'
-      )} Rename or remove ${chalk.yellow(
+      )} already exists in ${chalk.blue(outerFolder)}.`
-        `${outerFolder}/docs-examples-from-docusaurus`
-      )} to regenerate example docs.\n`
     );
   } 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(
+      `- ${chalk.green(
-        'Example blog posts already exist!'
+        'blog-examples-from-docusaurus'
-      )} Rename or remove ${chalk.yellow(
+      )} already exists in ${chalk.blue(`${outerFolder}/website`)}.`
-        `${outerFolder}/website/blog-examples-from-docusaurus`
-      )} to regenerate example blog posts.\n`
     );
   } else {
     fs.copySync(
@@ -155,20 +151,33 @@ if (feature === 'translations') {
     exampleSiteCreated = true;
     blogCreated = true;
   }
-  // copy .gitignore file
+
-  let gitignoreName = '.gitignore';
+  const copyFileToProjectFolder = (fileNameFrom, fileNameTo) => {
-  if (fs.existsSync(`${CWD}/../.gitignore`)) {
+    const copiedFileName = fileNameTo || fileNameFrom;
-    gitignoreName = '.gitignore-example-from-docusaurus';
+    const src = path.join(folder, fileNameFrom);
+    const dest = path.join(CWD, '..', copiedFileName);
+    if (fs.existsSync(dest)) {
       console.log(
-      `${chalk.yellow('.gitignore already exists')} in ${chalk.yellow(
+        `- ${chalk.green(copiedFileName)} already exists in ${chalk.blue(
-        CWD
+          outerFolder
-      )}. Creating an example gitignore file for you to copy from if desired.\n`
+        )}.`
       );
+    } else {
+      fs.copySync(src, dest);
     }
-  fs.copySync(
+  };
-    path.join(folder, 'gitignore'),
+
-    path.join(CWD, `/../${gitignoreName}`)
+  // copy .gitignore file
-  );
+  copyFileToProjectFolder('gitignore', '.gitignore');
+
+  // copy Dockerfile file
+  copyFileToProjectFolder('Dockerfile');
+
+  // copy docker-compose.yml file
+  copyFileToProjectFolder('docker-compose.yml');
+
+  // copy .dockerignore file
+  copyFileToProjectFolder('dockerignore', '.dockerignore');
 
   // copy other files
   const files = glob.sync(`${folder}/**/*`);
@@ -179,6 +188,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'
     ) {
@@ -193,11 +205,11 @@ if (feature === 'translations') {
       exampleSiteCreated = true;
     } catch (e) {
       console.log(
-        `${chalk.yellow(
+        `- ${chalk.green(
-          `${path.basename(filePath)} already exists`
+          `${path.basename(filePath)}`
-        )} in ${chalk.yellow(
+        )} already exists in ${chalk.blue(
-          `website${filePath.split(path.basename(filePath))[0]}`
+          `${outerFolder}/website${filePath.split(path.basename(filePath))[0]}`
-        )}. Rename or remove the file to regenerate an example version.\n`
+        )}.`
       );
     }
   });

website/sidebars.json

@@ -4,7 +4,8 @@
       "installation",
       "site-preparation",
       "site-creation",
-      "publishing"
+      "publishing",
+      "docker"
     ],
     "Guides": [
       "adding-blog",