Skip to content

Sample setup 2

Jump to bottom
Fons van der Plas edited this page Mar 27, 2025 · 2 revisions

Part 2: setting up the web server

For this step, we'll assume a very specific but also common setup:

  • Ubuntu-based server with apt-get, git, vim and internet
  • access through SSH
  • root access
  • port 80 and 8080 are open to the web

The easiest way to get this is to rent a server from digitalocean, AWS, Google Cloud, hetzner, etc. This setup was tested with digitalocean.com, which has an easy interface for beginners.

Required memory, disk space, CPU power

When renting a server, you need to decide which "droplet size" you want. The bottleneck is memory – CPU power and disk space will always be sufficient. As minimum, you need 500MB + 300MB * length(notebooks). But if you use large packages, like Plots or DifferentialEquations, a notebook might need 1000MB memory.

There is no minimum requirement on CPU power, but it does have a big impact on launch time and responsiveness. We found that DigitalOcean "dedicated CPU" is noticably faster (more than 2x) in both areas than "shared CPU".

It is really important to make sure that you will be able to resize your server later, adding/removing memory as needed, to minimize your costs. For DigitalOcean, we have a specific tip: always start with the smallest possible droplet (512MB or 1000MB), and then resize memory/CPU to fit your needs, without resizing the disk. When resizing, DigitalOcean does not allow shrinking the disk size.

0. Update packages

sudo apt-get update
sudo apt-get upgrade

You should run systemd --version to verify that we have version 230 or higher.

1. Install Julia (run as root)

Follow the official instructions to install Julia at using juliaup. Probably:

curl -fsSL https://install.julialang.org | sh

Now, the julia command should be available. Log out and log in, and type julia --version in the terminal, and you should see something!

Afterwards, you need to make the julia command available to all users. Run this command to do so:

sudo ln -s /home/`whoami`/.juliaup/bin/julia /usr/local/bin/julia

2. get your repository

cd ~
git clone https://github.com/<user>/<repo-with-notebooks>
cd <repo-with-notebooks>
git pull

3. Create a service

TEMPFILE=$(mktemp)
cat > $TEMPFILE << __EOF__
[Unit]
After=network.service

StartLimitIntervalSec=500
StartLimitBurst=5

[Service]
ExecStart=/usr/local/bin/pluto-slider-server.sh
Restart=always
RestartSec=5
User=$(whoami)
Group=$(id -gn)

[Install]
WantedBy=default.target
__EOF__

sudo mv $TEMPFILE /etc/systemd/system/pluto-server.service

This script uses whoami and id -gn to automatically insert your username an group name into the configuration file. We want to run the PlutoSliderServer as your user, not as root.

4. Create the startup script

TEMPFILE=$(mktemp)
cat > $TEMPFILE << __EOF__
#!/bin/bash

# this env var allows us to side step various issues with the Julia-bundled git
export JULIA_PKG_USE_CLI_GIT=true

cd /home/<your-username>/<your-repo>  # ⛔️⚠️ Make sure to change to the absolute path to your repository. Don't use ~.
julia --project="pluto-slider-server-environment" -e "import Pkg; Pkg.instantiate(); import PlutoSliderServer; PlutoSliderServer.run_git_directory(\".\")"
__EOF__

sudo mv $TEMPFILE /usr/local/bin/pluto-slider-server.sh

Tip

If you want to use GLMakie, it might be necessary to set a display. In the script above, replace julia with

DISPLAY=:0 xvfb-run -a -n 100 -s '-screen 0 1024x768x24' julia

5. Permissions stuff

sudo chmod 744 /usr/local/bin/pluto-slider-server.sh
sudo chmod 664 /etc/systemd/system/pluto-server.service

6. Start & enable

sudo systemctl daemon-reload
sudo systemctl start pluto-server
sudo systemctl enable pluto-server

Tip

If you need to change the service file or the startup script later, re-run this step to update the daemon.

Your server should be running now!! The next steps will explain how to monitor your server, and where to see the notebooks in action.

7. View logs

# To see quick status (running/failed and memory):
systemctl -l status pluto-server

# To browse past logs:
sudo journalctl --pager-end -u pluto-server

# To see logs coming in live:
sudo journalctl --follow -u pluto-server

Important

These three commands are important! Write them down somewhere.

See https://github.com/JuliaPluto/PlutoSliderServer.jl/wiki/Monitoring for more tips!

8. Server available

Once you see this message in your logs, you know that the server is running:

Feb 14 13:13:15 surfje pluto-slider-server.sh[14810]: ┌ Info:
Feb 14 13:13:15 surfje pluto-slider-server.sh[14810]: │ Starting server...
Feb 14 13:13:15 surfje pluto-slider-server.sh[14810]: │ ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡
Feb 14 13:13:15 surfje pluto-slider-server.sh[14810]: └   address = "http://0.0.0.0:8080/"
Feb 14 13:13:15 surfje pluto-slider-server.sh[14810]: [ Info: Listening on: 0.0.0.0:8080, thread id: 1
Feb 14 13:13:15 surfje pluto-slider-server.sh[14810]: ┌ Info:
Feb 14 13:13:15 surfje pluto-slider-server.sh[14810]: │ Server started
Feb 14 13:13:15 surfje pluto-slider-server.sh[14810]: └ ≡≡≡≡≡≡≡≡≡≡≡≡≡≡

You can open a web browser to test it out! Check out "🌟 Conclusion" below.

9. Live updates

When you change the notebooks in the git repository, your server will automatically update (PlutoSliderServer keeps calling git pull every couple of seconds)!

When a notebook file changes, PlutoSliderServer will shut down the old version of that notebook, and start the new one. When notebook files are added or removed, they are added or removed from the server. If you have a lot of notebooks, this is a big speedup compared to always having to restart the entire server when a notebook file changes.

When the configuration file (PlutoDeployment.toml) changes, PlutoSliderServer will detect a change in configuration and shut down. Because we set up our service using systemctl, the server will automatically restart. (With the new settings)

10. 🌟 Conclusion

Yay! If everything went well, we now set up a web server with PlutoSliderServer. To see the result, you open a browser and go to the URL of your server. This looks like:

http://12.34.56.78:8080/

where 12.34.56.78 is the IP address of your server. You should see an index of your notebooks, and clicking on a notebook should give an interactive page! The first visit can take a long time to load (because of JIT).

Note

Not seeing anything? If you cannot visit the index web page, if you get "Connection refused", "Connection timeout", etc., then check the server logs. If the logs seem fine, then you have a networking issue, like a firewall. Is the IP address correct? The port 8080 might be blocked. It's possible that port 80 is available, see nginx instructions below. Ask your network administrator.

Clone this wiki locally