# what is disco

disco turns any ubuntu 24.04 linux server you control into a private paas, with zero‑downtime deployments and a hosted dashboard and cli that manage the server over a secure api. your application traffic and github webhooks go directly to your server, not through disco’s servers.

disco can deploy all sorts of fully static sites (with no backend - such as a frontend site), ssg sites (that are generated on each git push, and then served fully statically), and backend sites (python, node, go, etc.)

# tldr how to

- the easiest way to install disco is to ssh into your server, then run `curl -fsSL https://disco.cloud/install.sh | sh`
- after installing everything, the curl sh script above will print a url. follow it, login with github (oauth login only - no permissions are asked)
- create a self-hosted github app (the UI will guide the user) and authorize the repos you want to deploy with disco
- create a new project (i.e. web app) in the UI by picking a repo - make sure it has a disco.json and Dockerfile. creating a project will make a first deployment and point a new domain name to the deployed site
- from this point on, simply git push to the repo to deploy new changes - the deployments will be done using zero downtime
- to edit/add env vars, see build logs, or realtime logs, use the web UI
- to optionally connect a CLI to control this server (which would allow LLMs to control the server, see logs, deploy projects, etc.), go to "Setup CLI Access" in the web UI sidebar
  - the instructions will be to: install the CLI on your local development machine, and then run a CLI command to accept an invite which will let you control the same server & projects from the CLI

# prerequisites

- an Ubuntu 24.04 LTS server with SSH access
- a GitHub account (for repo access + optionally to access the UI)

# how to get started

there are two main ways of getting started:

## installing disco on a server via curl sh and managing it via the UI

1) the first way is less error-prone, but more user (not LLM) centric as it directs the user to a web UI.

ssh into a fresh server, and then run the install script:

```bash
curl -fsSL https://disco.cloud/install.sh | sh
```

at the end of the installation, you will get an installation URL:

```text
-> [6/7] Generating invite link...
-> [7/7] Installation complete!

Visit this URL to complete setup:

  https://dashboard.disco.cloud/i/...
```

this invitation url will bring you to a web dashboard.

you will first need to login using github (this is a a pure oauth login that doesn't ask for any permissions)

then you will accept the invitation - meaning that your Disco UI account (to which you login to using the github oauth login) - will now store a reference to your server's disco daemon

from this point on, all of the setup is done using the web ui.

to add the ability to talk to this server using the disco CLI, the following steps should be followed:

- in the dashboard, find the "Setup CLI Access" item in the left sidebar

- per the instructions on that page, install the disco CLI by running the following on the user's development machine (NOT the server):

```bash
curl https://cli-assets.letsdisco.dev/install.sh | sh
```

- follow the instructions on the "Setup CLI Access" page to accept an invite to this server. this will look like the following:

```bash
disco invite:accept https://disco.example.com/api-key-invites/hexhexhexhexhex
```

i.e. running this using the locally installed CLI will also give you access to the same server as you have access to using the web UI. from this point on, you can issue CLI commands to this server.

## installing disco and managing it using the CLI

2) the alternative way is to install the disco CLI first to the development machine, and then run the `disco init` command.

install the CLI by running the following on the user's development machine (NOT the server):

```bash
curl https://cli-assets.letsdisco.dev/install.sh | sh
```

the simplest way to use disco init is to pass it an ssh connection string - however! the connection string MUST have a domain name, not an ip, ie you must call it like this:

```bash
disco init root@disco.example.com
```

note as well that `disco.example.com` must be a dedicated A record pointing to the server, and that this domain name can never be re-used to deploy a project.

ie your disco server will have its own dedicated domain name - so it's better to not use something like "example.com" if you also want to deploy frontend/backend sites to example.com. the best is a subdomain like disco.example.com and then you can deploy web projects to the apex example.com , www.example.com , or any other domain

after running `disco init`, an API key will be written locally to ~/.disco/config.json that will allow the disco CLI to talk to the disco server/daemon. from this point on, all disco CLI commands will work

# github setup before deploying any project (using the CLI)

the very first step before creating/deploying any project is to create a self-hosted github app. the UI will guide the user to do this. if you are using the CLI, run:

```bash
disco github:apps:add
```

this will show an explanation prompt and ask if the CLI can open the url in a browser. in the browser, the user will be asked to confirm the new self hosted github app (which will be given a random name), and then the user will be asked to confirm which repo(s) they want to authorize - repos must be authorized so that they can be deployed using disco

after the github app is created, you can check that it does exist on the daemon by running `disco github:apps:list`

you can also run `disco github:repos:list` to see the list of auth'd repos that the disco daemon has access to via the github app

# deploying a project (using the CLI)

it is assumed that:
- you have a server running disco
- you have the CLI running locally (on your own development machine)
- your CLI can manage your disco server ie if you run `disco meta:info` that returns information from your server
- you have setup a github app and authorized the repo you want to deploy - running `disco github:repos:list` shows you a list containing that repo
- the repo you want to deploy has a disco.json and a Dockerfile

the first step is to setup a domain name (by setting up an ANAME, CNAME or A record) for the project, like `app.example.com` which points to the server (either to its IP (not recommended) or a CNAME pointing to the disco server domain name such as app.example.com -> disco.example.com)

then, you can run:

```bash
disco projects:add --name NAME --github USER/REPO --domain DOMAIN
```

replacing the values for NAME (a project name that will be used for other CLI commands), USER/REPO and DOMAIN

this will deploy the project - any information on sucess/failure will appear here (ie you will see the build logs in real time)

to deploy again (for example, if there was an error in the Dockerfile), edit the files locally, and then git add + commit + push.

calling git push will lead to a webhook being sent from github directly to the disco server daemon, and this will lead to a new deployment being created.

# example projects

node https://github.com/letsdiscodev/example-node-site
flask/python https://github.com/letsdiscodev/example-flask-site
static https://github.com/letsdiscodev/example-static-site
vite (static + build on git push) https://github.com/letsdiscodev/example-vite
go https://github.com/letsdiscodev/example-go-site
rust https://github.com/letsdiscodev/example-rust-site

# notes

Q: how to talk to multiple disco servers using the CLI
A: if the CLI can talk to a single server, simply running commands such as `disco meta:info` will work. otherwise, if the CLI has access to multiple servers, add the `--disco (SERVER)` option to your CLI commands. for example:

```bash
disco meta:info --disco disco.example2.com
```

# contact

the disco developers hang out on discord - https://discord.gg/7J4vb5uUwU