More complete instructions for how to run locally with docker?

[cvocvo]

Hello,

I was looking at this as nice, light-weight documentation platform that I could run in my home lab to consolidate systems/services/network documentation.

Could you help me with some more basic steps for how to run this locally in docker?
I see this:

Alternatively, you can run it inside Docker while developing your site

$ docker-compose up

Currently, I'm running Portainer to manage my docker containers and have previously only deployed docker images.
Do I need to make a new container, get into the CLI, git pull this repo, and then run it somehow? Or can I just use the docker-compose.yaml somehow to spin up a new container and start writing content?

Thank you!

EDIT -- I asked ChatGPT and this is what it came up with -- is this correct/close?

To deploy Just the Docs software in a Docker container with Portainer, you can follow these steps:

1. Install Docker: Ensure that Docker is installed on your system. You can find instructions for your specific operating system on the Docker website.

2. Set up Portainer: Install and set up Portainer, a web-based Docker management interface, on your Docker host. You can find instructions for installing Portainer on their official website.

3. Create a Dockerfile: Create a Dockerfile to define the Docker image for Just the Docs. Open a text editor and save the following content as Dockerfile:

   # Base image
   FROM jekyll/jekyll:latest
   
   # Set working directory
   WORKDIR /site
   
   # Copy the website source code
   COPY . /site
   
   # Install dependencies
   RUN bundle install
   
   # Expose port
   EXPOSE 4000
   
   # Set default command
   CMD ["jekyll", "serve", "--host", "0.0.0.0"]

   This Dockerfile starts from the jekyll/jekyll base image, sets the working directory, copies the website source code, installs dependencies, exposes port 4000 (the default for Just the Docs), and sets the default command to start the Jekyll server.

4. Build the Docker image: Open a terminal or command prompt, navigate to the directory containing the Dockerfile, and run the following command to build the Docker image:

   docker build -t just-the-docs .

   This command builds the Docker image with the tag just-the-docs.

5. Deploy with Portainer: Open Portainer in your web browser and log in to the Portainer interface. Follow the steps to connect Portainer to your Docker host if you haven't done so already.

6. Create a new stack: In the Portainer interface, go to "App Templates" and click "Add Template". Fill in the required information to create a new stack:

   • Name: Enter a name for the stack.

   • Repository URL: Enter the repository URL of your Just the Docs project (e.g., https://github.com/username/repository).

   • Compose file: Select "Docker-compose (version 3)".

   • Web editor: Remove the default content and enter the following:

     version: '3'
     
     services:
       just-the-docs:
         image: just-the-docs
         ports:
           - 4000:4000
         volumes:
           - /path/to/your/just-the-docs:/site

     Replace /path/to/your/just-the-docs with the actual path to your Just the Docs project directory.

7. Deploy the stack: Click "Create the stack" to deploy the Just the Docs container. Portainer will pull the Docker image, create the container, and expose port 4000.

8. Access Just the Docs: Once the stack is deployed, you can access Just the Docs by visiting http://<your-docker-host>:4000 in your web browser. Replace <your-docker-host> with the hostname or IP address of your Docker host.

By following these steps, you should be able to deploy Just the Docs software in a Docker container using Portainer.

EDIT #2

Replace /path/to/your/just-the-docs with the actual path to your Just the Docs project directory.

I think may be this is probably something instead like:

• Make a volume in portainer
• Git clone https://github.com/just-the-docs/just-the-docs/ into that directory
• Then that path is the path to the volume?

Edit 3: If edit 2 is correct, then these are the ChatGPT generated steps for that.

Yes, you're on the right track. Here's how you can replace /path/to/your/just-the-docs with the actual path to your Just the Docs project directory using Portainer:

1. Create a volume in Portainer: In Portainer, go to "Volumes" and click "Add Volume". Give the volume a name (e.g., just-the-docs-volume) and specify the mount point, which is the path to your Just the Docs project directory on your Docker host machine (e.g., /path/to/your/just-the-docs). Save the volume.

2. Git clone Just the Docs repository: On your Docker host machine, open a terminal or command prompt and navigate to the directory where you want to clone the Just the Docs repository. Then, run the following command to clone the repository:

   git clone https://github.com/just-the-docs/just-the-docs.git

   This will create a directory called just-the-docs containing the Just the Docs project files.

3. Use the volume path: In the Portainer interface, when creating the stack, you will replace /path/to/your/just-the-docs with the mount point of the volume you created in Step 1. For example, if you named the volume just-the-docs-volume and specified the mount point as /path/to/your/just-the-docs, you would use that path in the Compose file:

   version: '3'
   
   services:
     just-the-docs:
       image: just-the-docs
       ports:
         - 4000:4000
       volumes:
         - just-the-docs-volume:/site
   
   volumes:
     just-the-docs-volume:

   In this example, just-the-docs-volume is the name of the volume you created, and it is mounted at /site within the container.

By following these steps, you should be able to clone the Just the Docs repository and use the path to the volume created in Portainer as the actual path to your Just the Docs project directory.

[max06]

Hello @cvocvo - sorry for the late reply!

There are mulitple options how to run just-the-docs within your local network. The easiest of those is using the core functionality of jekyll (jtd is just a theme) to generate a static site. Running bundle exec jekyll build basically creates a directory called _site with a ready to use version of your documentation. You can put this directory on any webserver, or even simply open the index.html page in your webbrowser.

A more advanced way to use our theme will be the integrated devcontainer I'm currently working on. You just need docker for that. There is no need to write your own dockerfiles or anything else. It's currently an open pull request in our template repository (https://github.com/just-the-docs/just-the-docs-template) and will hopefully be merged soon for you to use it. Said devcontainer is a regular docker container, don't get irritated by its name. You can use the same container to build and run your documentation whereever you want. Detailed instructions will be included!

I hope this helps you a bit already. If there are more questions, feel free to ask!

[hamoid]

I tried but Dev Container was not showing up in my vscodium, so I reverted to gem "jekyll", "~> 4.2.0" in Gemfile and then Docker works again (with the latest just-the-docs). I'll leave it like this and avoid touching it unless it stops working :-)

I wish it was possible to use Hugo or Zola, which are just one "small" executable to build the site.

Thanks for answering my question! :-)

[max06]

I tried but Dev Container was not showing up in my vscodium

That's why I recommended vscode - the extension is signed and encrypted ;)

[mattxwang]

Hm, I don't personally use the Dockerfile at all when developing the theme, so it's likely that it's out of date. Thanks for flagging this @cvocvo and @hamoid, I can add this to my backlog and see what I can do.

[cvocvo]

@mattxwang That'd be great, thank you! Ideally, I'd love to just pull a docker image, write some documentation, hit a button or run a script to recompile documentation.

[nmihaica]

@cvocvo +1