Help:Toolforge/My first static tool
Static webservices are one of the simplest. They just serve static files (html, js, css, ...) without running any specific language by themselves.
This stub webservice is designed to get a sample of a static application installed onto Toolforge using the new build service, as quickly as possible. The application makes use of the uwsgi python webserver, but does not run any code, just serves static files. You could use something similar with other languages/buildpacks.
The guide will teach you how to:
- Create a new tool
- Serve a static pages webservice on Kubernetes
Getting started
Prerequisites
Skills
- Basic knowledge of SSH
- Basic knowledge of the Unix command line
- Basic knowledge of Git
Accounts
Step-by-step guide
Step 1: Create a new tool account
- Follow the Toolforge quickstart guide to create a Toolforge tool and SSH into Toolforge.
- For the examples in this tutorial,
sample-static-buildpack-app
is used to indicate places where your unique tool name is used in another command.
- For the examples in this tutorial,
- Make sure to create a git repository for the tool, you can get one like this:
- Log into the toolforge admin page
- Select your tool
- On the left side panel, under
Git repositories
clickcreate repository
- Copy the url in the
Clone
section- There's a private url, that we will use to clone it locally, starting with "git":
git@gitlab.wikimedia.org:toolforge-repos/sample-static-buildpack-app.git
- And a public one, that we will use to build the app in toolforge, starting with "https":
https://gitlab.wikimedia.org/toolforge-repos/sample-static-buildpack-app.git
- There's a private url, that we will use to clone it locally, starting with "git":
Step 2: Install and configure uwsgi to serve static files
- What is uWsgi?
uWSGI is a popular web server for Python code.
How to create a basic uWSGI webservice
- Clone your tool git repository
You will have to clone the tool repository to be able to add code to it, on your local computer (with git installed) you can run:
laptop:~$ git clone git@gitlab.wikimedia.org:toolforge-repos/sample-static-buildpack-app.git
laptop:~$ cd sample-static-buildpack-app
That will create a folder called sample-static-buildpack-app
. We are going to put the code in that folder.
- Add the uwsgi dependency
requirements.txt
to keep track of the library dependencies of applications.laptop:~sample-static-buildpack-app$ cat > requirements.txt << EOF
uwsgi
EOF
- Add the uwsgi configuration
We could also pass all the options on the Procfile
directly, but having them in a file of it's own is easier to manage. So we create the file uwsgi.ini
:
laptop:~sample-static-buildpack-app$ cat > uwsgi.ini << EOF
[uwsgi]
http-socket = :$(PORT)
master = true
processes = 4
die-on-term = true
memory-report = true
check-static = html/
static-index = index.html
EOF
laptop:~sample-static-buildpack-app$ cat > Procfile << EOF
web: uwsgi uwsgi.ini
EOF
- Create the folder holding the files
The check-static
option above is the place where we will be putting our files, and index.html
is the file that will be loaded when going to the root url. So now we have to add some content there:
laptop:~sample-static-buildpack-app$ mkdir html
laptop:~sample-static-buildpack-app$ cat > html/index.html << EOF
<!DOCTYPE html>
<html>
<body>
<h1>Sample static site on Toolforge using the build service!</h1>
<p>You can find the code for this application <a
href="https://gitlab.wikimedia.org/toolforge-repos/sample-static-buildpack-app">here.</a>
</p>
</body>
</html>
EOF
- Commit your changes and push
laptop:~sample-static-buildpack-app$ git add .
laptop:~sample-static-buildpack-app$ git commit -m "First commit"
laptop:~sample-static-buildpack-app$ git push origin main
EOF
- Build the image
Now we have to ssh to login.toolforge.org
and start the build for the image:
laptop:~sample-static-buildpack-app$ ssh login.toolforge.org # or the equivalent with PuTTY
dcaro@tools-sgebastion-10$ become sample-static-buildpack-app
tools.sample-static-buildpack-app@tools-sgebastion-10$ toolforge build start https://gitlab.wikimedia.org/toolforge-repos/sample-static-buildpack-app.git
- Wait for the build to finish
By default it will show you the logs of the build in real time, but if you ctrl-C
or lose the session, you can check the status of the build like this:
tools.sample-static-buildpack-app@tools-sgebastion-10:~$ toolforge build show
You have to wait for the status to be ok(Succeeded)
.
- Start the webservice
tools.sample-static-buildpack-app@tools-sgebastion-10$ toolforge webservice buildservice start --mount=none
Starting webservice.
Once the webservice is started, navigate to https://sample-static-buildpack-app.toolforge.org
in your web browser, and see a 'Sample static site on Toolforge using the build service!' message. It might take a few minutes until it is reachable for the first time.
Notes
You can see the code used in this example here: https://gitlab.wikimedia.org/toolforge-repos/sample-static-buildpack-app
Troubleshooting
See Help:Toolforge/Build_Service#Troubleshooting.
Communication and support
Support and administration of the WMCS resources is provided by the Wikimedia Foundation Cloud Services team and Wikimedia movement volunteers. Please reach out with questions and join the conversation:
- Chat in real time in the IRC channel #wikimedia-cloud connect or the bridged Telegram group
- Discuss via email after you have subscribed to the cloud@ mailing list
- Subscribe to the cloud-announce@ mailing list (all messages are also mirrored to the cloud@ list)
- Read the News wiki page
Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself
Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)