Video tutorials on how to setup, use, add jobs, etc.

[mpolomdeepsense]

Think about the most crucial elements of setting up and using the Racetrack.

Ideas:

• How to set up Racetrack.
• Everything about jobs (create, upload, update manifest, etc.)
• Administrating/Managing Racetrack.

[iszulcdeepsense]

I think it would be really nice to have even a short, soundless GIF on the Racetrack's home page. Such a short demo could present typical use case: job deployment, dashboard and swaggerUI.

I wouldn't make more than one video. As for documentation, I strongly prefer written form. If something's missing, we should fill out the Markdown docs first.

[JosefAssadERST]

Agree with @iszulcdeepsense one of the videos should be fairly brief, probably oundless, and show the primary use case of RT: I write a simple python snippet, then with 15 seconds on the CLI it's deployed to a k8s cluster and I can curl it and see its swagger and so on. Said python should be as few lines as possible.

As for:

How to set up Racetrack. Everything about jobs (create, upload, update manifest, etc.) Administrating/Managing Racetrack.

Those are good ideas, but they're pretty comprehensive. I was imagining something more bite sized, but it's possible your idea is better. Not sure.

[iszulcdeepsense]

I propose to make a silent video with subtitles for a home page, according to the following playbook:

0. (Assuming we've got Racetrack deployed locally and plugins are installed)
1. User creates the short model class in entrypoint.py (something fancier than adding 2 numbers, maybe checking if a number is prime or some ML model)
2. User creates job.yaml as concise as possible.
3. Runs racetrack deploy
4. Goes to dashboard in a browser, navigates to the job and clicks "Open"
5. In a SwaggerUI, user calls a job with some arguments and gets the result.
6. The end, closing credits...

[mpolomdeepsense]

So, after few hours of work I managed to come up with something like this, 40s video. Probably few things could be done better like curl response is in the same line as a new line, it's not well readable at first. Also, I'm not a master at exporting such videos so the best I have right now is 2,7 MB mp4. The gifs I tried to export had a really bad quality, this one is not that big and has a good enough quality.

This one will probably be replaced with a dashboard showcase but for now, i did something like this just to show what I think it could look like

https://github.com/TheRacetrack/racetrack/assets/124889668/b2ffda1c-9e45-4c6a-8f36-6f3920826e75

[JosefAssadERST]

I disagree about making it something less trivial than adding two integers.

The first 17 seconds of a 40 second (43% of the entire demo reel) demo reel have nothing to do with RT, it's about making a directory and opening an editor and writing python code in a file.

I think:

1. Just make an adder
2. have the python file already, just cat it to stdout in the video
3. (maybe) also already have the manifest. Not decided, could go either way.
4. Use vim so you don't leave the CLI. Makes the demo feel tighter if you don't see the demo'er alt-tabbing.

[mpolomdeepsense]

@JosefAssadERST

https://github.com/TheRacetrack/racetrack/assets/124889668/90d3ddfc-39c8-4125-9200-c5eabab00ae0

[JosefAssadERST]

Just my personal opinion, but that's a lot more to the point. @iszulcdeepsense what do you think?

Also, I have a vague feeling a lot of people use asciinema, would that make your life easier in any capacity?

[mpolomdeepsense]

I was using Peek, it's for recording any part of the screen. asciinema might be better for this recording but if we also want to showcase a dashboard i don't think it will be better for the other ones.

[mpolomdeepsense]

Also, what would you prefer the video to look like? I mean the style of a recording. Full screen recording with little cuts and edits or something more like the first video I made, with more transitions, only the window (the one we work in) is visible at one time?

[JosefAssadERST]

I think the first is simpler therefore better. Also simpler is easier to replace later since we didn't invest ten months in producing it. :)

[mpolomdeepsense]

@iszulcdeepsense @JosefAssadERST

Is something like this enough to present the basics of the dashboard? Obviously, there needs to be subtitles added but I'm just talking about the overall functionalities shown in the video.

https://github.com/TheRacetrack/racetrack/assets/124889668/52dc65e2-eb92-4c41-838b-66e6e3716536

[JosefAssadERST]

I think that's good. Two proposed changes:

1. I'd skip the part where you enter the auth token; execute in the built-in swagger doesn't require it
2. You can use I think it was parameter defaults, and they will appear as a sample payload in the swagger payload box.

Beyond that I think it's perfect. Really shows the full basic cycle. Dashboard can do a lot more but that's not our purpose here.

[iszulcdeepsense]

Couple of remarks from me:

1. I liked it when you recorded just the small window (as in first video), not the whole screen. So you don't need to go full-screen to see anything. I believe the browser window can be also reduced to the small size.
2. @mpolomdeepsense It looks nice when you type the manifest file on the run. What tool did you use to simulate the typing? Or was it you?
3. It felt pleasant to watch it at increased speed (at the first video) - deployment felt blazingly fast :smiley: .
4. I hope we can make the video reproducible and semi-automated by at least writing down the screenplay steps in a file and to simulate the keyboard input, while recording.
5. Agree on auth token in SwaggerUI - you don't need that step.
6. Printing files with cat in terminal looks odd - it's barely readable. It would be more intelligible to open vim with syntax highlighting and type in the content (auto-fill it expeditiously, not spending much time on it).
7. Agree with Marek, asciinema is not an option as we want to show the Dashboard as well.
8. MP4 format is a good choice, it can be nicely embedded in Github's Markdown. Let's upload it here in this issue and link to it in the docs to prevent keeping that file in git

Generally speaking, it looks very nice. Good job, @mpolomdeepsense , you grasped the Racetrack's spirit :smile: .

[mpolomdeepsense]

@iszulcdeepsense

What tool did you use to simulate the typing?

https://marketplace.visualstudio.com/items?itemName=dansilver.typewriter As for the terminal, I had to type it myself.

It felt pleasant to watch it at increased speed (at the first video)

Yeah, there is actually a cut between the steps, that's why it feels so fast. And on top of that video was sped up to something like x2.5 - 3.

I hope we can make the video reproducible and semi-automated by at least writing down the screenplay steps in a file and to simulate the keyboard input, while recording.

Yeah, that's doable. For sure there will be a list of steps, captions, used tools, files etc. I could also record my keyboard while recording. Do you know some nice tools for it?

[iszulcdeepsense]

I could also record my keyboard while recording. Do you know some nice tools for it?

@mpolomdeepsense It can be done fairly simple with Python. I used something like this once:

import random
import subprocess
import time

def type_line(line: str):
    for character in line:
        character = character.replace('"', '\\"')
        shell(f'xdotool key type "{character}"')
        time.sleep(0.1 * random.uniform(0.5, 1))
    time.sleep(0.3)
    shell('xdotool key Return')

def shell(cmd: str):
    subprocess.Popen(cmd, shell=True).wait()

type_line('print("Hello")')

[JosefAssadERST]

Good job, @mpolomdeepsense , you grasped the Racetrack's spirit

Yep, bang on. Go for it.

[mpolomdeepsense]

Script for first video (short one). Will look basically the same as the current one, with some minor changes.

Title screen caption: Racetrack - Python job and CLI showcase

1. Use Vim to display is_prime job contents (is_prime.py files and job.yaml configuration)
2. Input deploy command (racetrack deploy ./is_prime/ --remote http://localhost:7102)
3. Wait for it to finish deploying
4. Make first curl call, paste: curl -X POST "http://localhost:7105/pub/job/prime_checker/latest/api/v1/perform" -H "Content-Type: application/json" -H "X-Racetrack-Auth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZWVkIjoiY2UwODFiMDUtYTRhMC00MTRhLThmNmEtODRjMDIzMTkxNmE2Iiwic3ViamVjdCI6ImFkbWluIiwic3ViamVjdF90eXBlIjoidXNlciIsInNjb3BlcyI6bnVsbH0.xDUcEmR7USck5RId0nwDo_xtZZBD6pUvB2vL6i39DQI", then insert -d '{"n": 7}' at the end. Execute it.
5. Make a second curl call. Same as the previous one but input -d '{"n": 10}' instead.

Record using asciinema

Video edited with 0.5s fade-in and fade-out animations. All sped up 2-3 times.

[mpolomdeepsense]

Script for second video (dashboard showcase). Still needs keyboard input recording, editing instructions, used tools etc., only overview with captions between scenes finished.

Title screen caption: Racetrack - Python job and dashboard showcase

Caption 1: After setting up the Racetrack we can begin creating our first Python job. It should consist of job.yaml configuration file and desired .py files.

Scene 1: Turn on the VSC (or some other IDE) and show the contents of job files.

Caption 2: Now, when we have our first job ready, we can deploy it with this command: racetrack deploy JOB_PATH --remote RACETRACK_URL.

Scene 2: Open the terminal and input the deploy command on the previously created job. Wait for it to finish deploying.

Caption 3: By using the Racetrack dashboard we can e.g.: browse, modify, rebuild and redeploy, delete jobs. We can access it through the browser. From the dashboard, we can also access the job's SwaggerUI where it's possible to make requests to the job.

Scene 3: Open the browser and go to the Racetrack dashboard page. Log in as admin (login: admin, password: admin). It should redirect you to the list of running jobs. Select the one that was just added and click on a blue OPEN button. It will redirect you to the job's SwagerUI. There go to /perform endpoint and test the job by entering the request's body. After that go back to the dashboard and delete the job.

[mpolomdeepsense]

So the second video will probably be recorded using OBS. Same fade-in/out animations as in the first video. Captions will be shown in between cuts on the blurred background of the next scene. Also, some fading animations when captions appear/disappear.

What do you think about that?

[iszulcdeepsense]

• Not really sure about splitting into 2 videos. I feel like it's a bit too much, some parts are the same (job files and deployment). What's the reason to make 2 videos?
• What I don't like about asciinema is that the player can't be embedded in the Markdown page, it redirects you to a new page. That's why I'm more inclined to MP4 - nice in-place player that you can pause at any time. Plus, it's probably easier to produce.
• Being in a job's directory would simplify the commands in my opinion.
• I think one curl call is enough. There's no need to prove it more.

To sum up:

0. (done before recording) mkdir primer, cd primer
1. vim entrypoint.py

   
   import math

class JobEntrypoint:

def perform(self, number: int) -> bool:
    """Check if a number is prime"""
    if number < 2:
        return False
    for i in range(2, int(math.sqrt(number)) + 1):
        if number % i == 0:
            return False
    return True

def docs_input_example(self) -> dict:
    """Return example input values for this model"""
    return {'number': 7907}

2. `vim job.yaml`
```yaml
name: primer
owner_email: sample@example.com
jobtype: python3:latest
git:
  remote: https://github.com/TheRacetrack/racetrack
jobtype_extra:
  entrypoint_path: 'entrypoint.py'
  entrypoint_class: 'JobEntrypoint'

3. racetrack deploy --remote http://localhost:7102

4. curl -X POST "http://localhost:7105/pub/job/primer/latest/api/v1/perform" \
   -H "Content-Type: application/json" \
   -H "X-Racetrack-Auth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZWVkIjoiY2UwODFiMDUtYTRhMC00MTRhLThmNmEtODRjMDIzMTkxNmE2Iiwic3ViamVjdCI6ImFkbWluIiwic3ViamVjdF90eXBlIjoidXNlciIsInNjb3BlcyI6bnVsbH0.xDUcEmR7USck5RId0nwDo_xtZZBD6pUvB2vL6i39DQI"` \
   -d '{"n": 7907}'

5. Then go see a dashboard, find it, open SwaggerUI and call it through the swagger.

[mpolomdeepsense]

What's the reason to make 2 videos?

Oh, I thought we wanted to do that from the start. One would go as a looped gif into readme/docs first page (max 30s, like the one here) and the second one in a proper video format, with more information, subtitles etc.

But if you want to combine these videos we can do that, why not. Making two videos seemed kinda weird to me since they were similar. I deducted from the previous discussion that you wanted two separate videos, that's why two scripts.

[iszulcdeepsense]

Alright, I thought about GIF initially, but gifs tend to be infuriating cause you can't pause them and take a closer look. That's why I'm pushing for MP4 now.

[iszulcdeepsense]

Now, I'm not so sure if subtitles are necessary. It's up to you

[mpolomdeepsense]

Here is a version without any captions.

https://github.com/TheRacetrack/racetrack/assets/124889668/d7b99acf-fcef-48f3-ac95-d4356c3acb0f

[iszulcdeepsense]

This looks really cool.

A browser's view could be zoomed in, but I'm just nitpicking - it's a note for the next recording. This is already great.

[mpolomdeepsense]

Here is a version with captions

https://github.com/TheRacetrack/racetrack/assets/124889668/43648168-897c-435f-b2e1-e4f8e0313d7a

[iszulcdeepsense]

Well, I was hoping to use this feature - add subtitles to HTML video player in a <video> player embedded in Markdown. While it works on mkdocs static pages, it doesn't seem to show up on Github. I'll check what the limitations are.

[iszulcdeepsense]

I can confirm that textual captions in a video player don't work on Github: https://github.com/TheRacetrack/racetrack/blob/286-video-tutorials-on-how-to-setup-use-add-jobs-etc/README.md while it works with our MkDocs documentation:

https://github.com/TheRacetrack/racetrack/assets/45496492/1fa3f9f6-90fb-4d9a-99f2-e7a0313eb6a7

Nevermind, let's stick to your plan - having captions hardcoded in a video.

[mpolomdeepsense]

Oh, didn't know drinking liquid nitrogen could kill me. Thanks for the warning. You truly are a life saver!