Skip to content
Space Works Docs

Quick start

This page takes you from an empty server to a running Space Works install with one command. The installer asks all its questions first, shows you a summary, and changes nothing on the machine until you confirm.

Before you start

Section titled “Before you start”

You need:

  • A 64-bit machine (x86_64; on arm64 you build the images yourself, see Requirements) running Linux (Debian/Ubuntu, Fedora/RHEL/Alma/Rocky, Arch or openSUSE). macOS also works, and so does Windows through Git Bash or WSL2, as long as Docker Desktop is installed and running.
  • On Linux, root or a user with sudo. The installer installs Docker, Docker Compose and curl for you after you confirm. curl (or wget) and tar must already be there.
  • Internet access to github.com and ghcr.io.
  • At least 8 GiB of free disk space.
  • A domain name is optional. The default is plain HTTP, which is fine for a trial or a local network. For automatic HTTPS you need a domain pointing at the server and an email address for the certificate.

Have these answers ready: the web address people will type (a host name or IP address), your makerspace name, and the admin username, email and password. You can leave the password blank and the installer generates a strong one.

See Requirements for the full list, including ports.

Install

Section titled “Install”

  1. Run the installer on the server, as your normal user:

    On the server
    curl -fsSL https://raw.githubusercontent.com/SpaceWorks-HQ/SpaceWorks/main/install.sh | bash

    It asks for your sudo password when it needs root. Piping to sudo bash also works if you want the install owned by root. To read the checklist without changing anything, download the script and run bash install.sh --help.

  2. Choose the repository. The first question is which GitHub repository to install and update from. Press Enter for the main project. If you run your own fork, type it as owner/name, or pass it up front:

    Terminal window
    curl -fsSL https://raw.githubusercontent.com/SpaceWorks-HQ/SpaceWorks/main/install.sh | bash -s -- --repo YourName/SpaceWorks

  3. Answer the setup questions. Press Enter to accept each default shown in brackets. In order, the installer asks about:

    • Hosting: one makerspace (default), several makerspaces at /m/<slug>, or a platform with a subdomain per makerspace.
    • Website: serve the website from this server (default), or run the API only.
    • HTTPS: plain HTTP (default), automatic HTTPS through Caddy, or your existing reverse proxy.
    • Containers: standard (default) or single box.
    • Storage: the bundled Silo object storage (default) or your own S3-compatible buckets.
    • Your makerspace: web address, name, then eight yes/no areas: Inventory & lending, Machines and Reports default to yes; Events, Bookings, Membership, Online payments and Chat alerts default to no. Each “yes” asks a few follow-up settings.
    • Admin account: username, email and password.
    • Optional extras: a Google sign-in client ID, Stripe keys (only with Online payments), and an optional GitHub Actions runner for automatic deploys (default no).

    Every question and default is explained in Setup questions.

  4. Review the summary and confirm. One summary lists every choice, the services that will run and what will change on the host, followed by Proceed? [Y/n]. Answer no and nothing is installed.

  5. Wait for it to finish. The installer installs anything missing, copies the release into /opt/spaceworks (set SPACEWORKS_DIR before bash to change this), writes private settings with generated secrets, pulls the pinned release images and starts everything. The first run takes a few minutes.

  6. Save the login details. At the end the installer prints your website address and admin username. If you let it generate the password, this is the only time it is shown. Write it down.

Open the app and sign in

Section titled “Open the app and sign in”

Open the website address the installer printed. These are the places you will use most:

Where Path Who it is for
Public catalogue /m/<slug> Everyone. <slug> is a URL-friendly form of your makerspace name, for example riverside-makerspace.
Staff console /admin Staff and the superadmin. Sign in here with the admin account you just created.
API and Swagger UI /api and /docs/ Developers and integrations.
Django control plane /control/ The superadmin only. Not served on the public website.

When a domain is dedicated to a single makerspace, that makerspace’s public pages are served from the domain root instead of /m/<slug>.

Make it useful

Section titled “Make it useful”

Sign in to the staff console at /admin, then:

  1. Add your inventory: the tools and equipment people can borrow.
  2. Check the public catalogue at /m/<slug> and adjust what each item shows publicly.
  3. Add your team and give each person a role. See Roles and permissions.
  4. Review your modules and switch on the parts of Space Works your space actually uses. See Modules.
  5. Optionally connect email and chat alerts. See Email and Notifications.

Makerspace setup walks through this in detail.

Update later

Section titled “Update later”

Run the same curl … | bash command again on a server that already has Space Works, and the installer shows a menu instead of reinstalling:

  1. Update to the latest release (backs up the database first).
  2. Change modules only.
  3. Update, then change modules.
  4. Cancel (the default).

See Updates for manual updates and automatic deploys.

Try it locally

Section titled “Try it locally”

You can try Space Works on your own computer before you pick a server.

Install Docker Desktop and start it, then run the same one-line installer from a terminal (Git Bash or WSL2 on Windows). When it asks for the web address, type localhost and keep plain HTTP. When it finishes, open http://localhost/admin and sign in with the admin account it printed.

On Windows Git Bash, choose an install folder you own, for example:

Terminal window
curl -fsSL https://raw.githubusercontent.com/SpaceWorks-HQ/SpaceWorks/main/install.sh | SPACEWORKS_DIR="$HOME/SpaceWorks" bash

Next steps

Section titled “Next steps”