Skip to content

Latest commit

 

History

History
172 lines (124 loc) · 9.96 KB

quick-start.md

File metadata and controls

172 lines (124 loc) · 9.96 KB
Raw

Quick Start

Welcome to Shipyard! So glad you're here 😊 In a couple of minutes, you'll have your new dashboard up and running 🚀

TLDR; Run docker run -p 8080:8080 khulnasoft/shipyard, then open http://localhost:8080

1. Prerequisites

The quickest and easiest method of running Shipyard is using Docker (or another container engine). You can find installation instructions for your system in the Docker Documentation. If you don't want to use Docker, then you can use one of Shipyard's other supported installation methods instead, all of which are outlined in the Deployment Docs.

2. Installation

To pull the latest image, and build and start the app run:

docker run -d \
  -p 8080:8080 \
  -v ~/my-conf.yml:/app/user-data/conf.yml \
  --name my-dashboard \
  --restart=always \
  khulnasoft/shipyard:latest

Either replace the -v path to point to your config file, or leave it out. For a full list of available options, then see Shipyard with Docker Docs. If you'd prefer to use Docker Compose, then see Shipyard with Docker Compose Docs. Alternate registries, architectures and pinned versions are also supported.

Your dashboard should now be up and running at http://localhost:8080 (or your servers IP address/ domain, and the port that you chose). The first time you build, it may take a few minutes.

3. User Data Directory

Your config file should be placed inside user-data/ (in Docker, that's /app/user-data/).

This directory can also contain some optional assets you wish to use within your dashboard, like icons, fonts, styles, scripts, etc.

Any files placed here will be served up to the root of the domain, and override the contents of public/. For example, if you had user-data/favicon.ico this would be accessible at http://my-shipyard-instance.local/favicon.ico

Example Files in user-data:

  • conf.yml - This is the only file that is compulsary, it's your main Shipyard config
  • **.yml - Include more config files, if you'd like to have multiple pages, see Multi-page support for docs
  • favicon.ico - The default favicon, shown in the browser's tab title
  • initialization.html - Static HTML page displayed before the app has finished compiling, see public/initialization.html
  • robots.txt - Search engine crawl rules, override this if you want your dashboard to be indexable
  • manifest.json - PWA configuration file, for installing Shipyard on mobile devices
  • index.html - The main index page which initializes the client-side app, copy it from /public/index.html
  • **.html - Write your own HTML pages, and access them at http://my-shipyard-instance.local/my-page.html
  • fonts/ - Custom fonts (be sure to include the ones already in public/fonts
  • item-icons/ - To use your own icons for items on your dashboard, see Icons --> Local Icons
  • web-icons/ - Override Shipyard logo
  • widget-resources/ - Fonts, icons and assets for custom widgets

4. Configure

Now that you've got Shipyard running, you are going to want to set it up with your own content. Config is written in YAML Format, and saved in /user-data/conf.yml. The format on the config file is pretty straight forward. There are three root attributes:

  • pageInfo - Dashboard meta data, like title, description, nav bar links and footer text
  • appConfig - Dashboard settings, like themes, authentication, language and customization
  • sections - An array of sections, each including an array of items
  • pages - Have multiples pages in your dashboard

You can view a full list of all available config options in the Configuring Docs.

pageInfo:
  title: Home Lab
sections: # An array of sections
- name: Example Section
  icon: far fa-rocket
  items:
  - title: GitHub
    description: Shipyard source code and docs
    icon: fab fa-github
    url: https://github.com/khulnaSoft/shipyard
  - title: Issues
    description: View open issues, or raise a new one
    icon: fas fa-bug
    url: https://github.com/khulnaSoft/shipyard/issues
- name: Local Services
  items:
  - title: Firewall
    icon: favicon
    url: http://192.168.1.1/
  - title: Game Server
    icon: https://i.ibb.co/710B3Yc/space-invader-x256.png
    url: http://192.168.130.1/

Notes:

  • You can use a Docker volume to pass a config file from your host system to the container
    • E.g. -v ./host-system/my-local-conf.yml:/app/user-data/conf.yml
  • It's also possible to edit your config directly through the UI, and changes will be saved in this file
  • Check your config against Shipyard's schema, with docker exec -it [container-id] yarn validate-config
  • You might find it helpful to look at some examples, a collection of which can be found here
  • It's also possible to load a remote config, e.g. from a GitHub Gist

5. Further Customisation

Once you've got Shipyard setup, you'll want to ensure the container is properly healthy, secured, backed up and kept up-to-date. All this is covered in the Management Docs.

You might also want to check out the docs for specific features you'd like to use:

  • Authentication - Setting up authentication to protect your dashboard
  • Alternate Views - Using the startpage and workspace view
  • Backup & Restore - Guide to Shipyard's cloud sync feature
  • Icons - Outline of all available icon types for sections and items
  • Localisation - How to change language, or add your own
  • Status Indicators - Using Shipyard to monitor uptime and status of your apps
  • Search & Shortcuts - Using instant filter, web search and custom hotkeys
  • Theming - Complete guide to applying, writing and modifying themes and styles

6. Final Note

If you need any help or support in getting Shipyard running, head over to the Discussions page. If you think you've found a bug, please do raise it so it can be fixed. For contact options, see the Support Page.

If you're enjoying Shipyard, and have a few minutes to spare, please do take a moment to look at the Contributing Page. Huge thanks to everyone who has already helped out!

Enjoy your dashboard :)

Alternative Deployment Method 1 - From Source

You can also easily run the app on your system without Docker. For this Git, Node.js, and Yarn are required.

git clone https://github.com/khulnaSoft/shipyard.git && cd shipyard
yarn # Install dependencies
yarn build # Build the app
yarn start # Start the app

Then edit ./user-data/conf.yml

Alternative Deployment Method 2 - Netlify

Don't have a server? No problem! You can run Shipyard for free on Netlify (as well as many other cloud providers). All you need it a GitHub account.

  1. Fork Shipyard's repository on GitHub
  2. Log in to Netlify with GitHub
  3. Click "New site from Git" and select your forked repo, then click Deploy!
  4. You can then edit the config in ./user-data/conf.yml in your repo, and Netlify will rebuild the app

Alternative Deployment Method 3 - Cloud Services

Shipyard supports 1-Click deployments on several popular cloud platforms. To spin up a new instance, just click a link below: