Installation Setup

View production requirements in Preparation documentation before continuing.

Clone Repository

Clone the ButterflyVu repository using the git:

git clone https://ark.sudovanilla.org/korbs/ButterflyVu/
cd ./ButterflyVu/

The compose branch is a template setup for running ButterflyVu in Docker, switch to branch:

git checkout compose

Directory Structure

ButterflyVu
| # Assets
├── assets
│   ├── icons # Sidebar Icons
│   ├── og # Open Graph
│      ├── background.png
│      └── logo.png
|   ├── favicon.ico
|   ├── logo.png
|
| # Overrides (Optional, not included with branch)
├── overrides
│      └──
|
| # Your Documentation
├── docs
│   ├── document.md
│   └── another-document.md
|
| # Root
├── compose.yml
└── config.json

Compose File

Choice of Architecture

The OCI images available for Docker and other container software are available for both amd64 and arm64 system architecture. By default, amd64 is already selected in the compose.yml file as it’s more common to see in servers. This is shown at the end of the OCI image name in the image section.

If your server does not run on either of the architecture, then you’ll need to build the OCI image on the server itself, if that is the case please continue to Building OCI Image.

Architecture	OCI Image
amd64	oci.registry.sudovanilla.org/butterflyvu:amd64
arm64	oci.registry.sudovanilla.org/butterflyvu:arm64

Networking and Ports

By default, port host 45000 is used for the ButterflyVu container in compose.yml. You are most welcome to change this port in compose.yml, however please do NOT change the container port which is 8500.

If for unknown reasons the ports aren’t being properly exposed, possibily under a janky Docker setup, you may need to open the network_mode to host. Switching network_mode means it’ll use the container port on the network instead, which would be 8500. This is rare situation and is not nessesary for most server environments.

Volumes

Docker volumes are used to presist data generated by and used by Docker containers, all volumes that are already included in compose.yml should not be removed, although you’re weclome to add volumes with caution.

By default, it should look like this:

...
volumes:
    # Assets
    - ./assets/icons:/vu/src/public/icons/
    - ./assets/og:/vu/src/public/og/
    - ./assets/favicon.ico:/vu/src/public/favicon.ico
    - ./assets/logo.png:/vu/src/public/logo.png

    # Your Documentation
    - ./docs/:/vu/src/content/docs/

    # Configuration
    - ./config.json:/vu/config.json
...

Also see Directory Structure.

Using volumes, you can also add files which should be used to override components in ButterflyVu, as an example for the footer:

...
- ./overrides/Footer.astro:/vu/src/components/global/Footer.astro
...

Also see Overriding Components.

Configuration

Some of the default configuration should be changed, such as:

• meta.site_title
• meta.copyright
• splash.title
• splash.description
• splash.actions.url (Should point to first document)
• splash.actions.secondary.text
• splash.actions.secondary.url
• cards
• links
• sidebar

For configuration options such as links and sidebar, please view their documentation in the Configuration section of the ButterflyVu documentation.

Assets

Just like with the Configuration section, you should probably some of the assets that are provided with this repository branch. Such as the logo, favicon, and Open Graph assets to match your product or brand.

Do not change format, as an example favicon.ico must be a .ico file and icons must be in the .svg format.

Documentation

You can now start adding your documentation, please them in ./docs/.

Launch

Retrieve the OCI image:

docker compose pull

Then launch:

docker compose up -d

Within a few moments, ButterflyVu will be able on http://localhost:45000.

If it still not available yet at the port 45000, then it may still be building or something was mis-configured resulting in error. To check the status, run the log command:

docker compose logs --follow