feat: add lesson about using the platform

[honzajavorek]

Introducing the final lesson of the course about deploying to the platform. This was quite challenging as with every other sentence I grappled with bugs or behavior, which wasn't really intuitive to me. On my journey I filed these:

• cli does not recognize Python project created by crawlee apify-cli#746
• Add docs about project structures supported by apify init apify-cli#761
• Rename apify init to apify actorize apify-cli#762
• Python Actors: Add option for using uv setup actor-templates#350
• The Python template uses system Python to create the virtual environment apify-cli#768
• The python-crawlee-beautifulsoup template produces a scraper which crashes as an Actor on Apify actor-templates#352
• Title of code examples doesn't display anymore (regression) #1497

I explored several approaches, which were dead ends. The lesson now takes an approach where it starts a new project from a template and replaces parts of the template with the original scraper. That completely avoids apify init and should be robust with regard to possible future changes, such as migrating to uv, and so on.

I find the UI of the Apify console rather confusing and super complex, especially navigation, even as a user who regularly visits the interface for the past year. Also the UI seems to remember my last location or something like that, so every time I open it, it defaults to a different tab. Once it's Input, other time it's Last run, etc.

I'm no UX designer, so I can't help with that, just sharing it here as a feedback and a fact, which I took into account when creating the lesson. The only way to mitigate the confusion which came to my mind was to provide as many screenshots as possible. Also I didn't dare to rely on where the student might land, and I make sure to re-iterate on which screen and in which tab they should be.

The lesson intentionally goes through updating the Actor so that the student knows how to do it and how to push new changes and build and run the Actor again and again. I opted to keep the student using the Input tab as the place from which they start the Actor, even though in reality they could press the Start button from other tabs too. I feel like that way it's less confusing, makes most sense, and they won't get distracted by all the other options that much.

I did my best to structure the lesson so that it leads from stating shortcomings of the current solution to understanding how the platform helps to solve them, because I think that's the most honest way to "sell" the platform.

Let me know what you think!

[metalwarrior665]

Thanks. Was there a discussion about where this content should live before? There is quite a lot of duplication both with https://docs.apify.com/platform and https://docs.apify.com/academy/apify-platform. The approach is JS was to have the scraping tutorial separate from the platform.

I'm not against having the whole thing follow in the Python course (as it can specialize to Python devs needs) but then we will have to maintain duplicate content which tends to be a bit annoying.

[honzajavorek]

@metalwarrior665 The discussion has happened here: #1015 (comment) I don't want a duplicate content, but this is a logical ending of the course:

1. basics in DevTools
2. basics in Python
3. use framework to simplify your code and get some other benefits (Crawlee)
4. deploy to a platform to get some other benefits (Apify)

The lesson is specific to the scraper we're building over the course of the lessons. You could say the same about the previous lesson about Crawlee, where the same content could be covered by Crawlee docs.

[vdusek]

Couldn't we use webp instead of png? The images would be about 5x smaller. Changes to the Python code are okay.

[honzajavorek]

I don't mind using webp, but it's just about the size of this repo. The site has the images optimized automatically, at least that's what I remember @B4nan saying somewhere else in the comments.

[B4nan]

The size of the repo is also important, if the difference is 5x let's just go with webp. We use them pretty much exclusively in the crawlee blog posts too for the same reason.

[honzajavorek]

I’m already putting new images through optimizt every time before commit, and it has an option to convert to webp. I just wonder if we could have it as a pre-commit so I don’t have to think about it. But changing extension breaks the path to the image, so I guess this must be a manual process… Unless I write myself a Python script to do the magic… 😅

…

On Tue 18. 3. 2025 at 17:24, Martin Adámek ***@***.***> wrote: The size of the repo is also important, if the difference is 5x let's just go with webp. We use them pretty much exclusively in the crawlee blog posts too for the same reason. — Reply to this email directly, view it on GitHub <#1424 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACFGMKHOE76ARI2IR25QZ32VBCD7AVCNFSM6AAAAABVUWEMUOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDOMZTHA4TQNJQG4> . You are receiving this because you authored the thread.Message ID: ***@***.***> [image: B4nan]*B4nan* left a comment (apify/apify-docs#1424) <#1424 (comment)> The size of the repo is also important, if the difference is 5x let's just go with webp. We use them pretty much exclusively in the crawlee blog posts too for the same reason. — Reply to this email directly, view it on GitHub <#1424 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACFGMKHOE76ARI2IR25QZ32VBCD7AVCNFSM6AAAAABVUWEMUOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDOMZTHA4TQNJQG4> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[honzajavorek]

I'm moving the discussion about images to a separate issue: #1549 Regarding this particular PR, the images here are technically already a part of this git repo now, so converting them would only add size, but if you want me to change them to webp, I'll do it.

[TC-MO]

I think that the structure that @honzajavorek proposed is the correct way of creating this course and integrating it with Academy. It aligns especially well with current work on trimming down Apify Platform content from Academy

[TC-MO]

Few questions & changes suggested otherwise LGTM

[TC-MO]

Can we change here from bold to emphasis? Usually we use bold across docs to highlight UI elements so I would prefer if we could keep it the same way here

[TC-MO]

same here could we change it to emphasis?

[TC-MO]

Might be opportunity to send to our docs? (though it should be trivial to sign-up so I'll just leave it up to your consideration) ¯\_(ツ)_/¯

[TC-MO]

we usually used `<YOUR_XYZ> as placeholders, not sure what is your experience with that. Is the mock username in that format better received by users?

[TC-MO]

Shouldn't this be broken up??

Suggested change

	Change to a directory where you start new projects in your terminal. Then, run the following command—it will create a new subdirectory called `warehouse-watchdog` for the new project, containing all the necessary files:
	```text
	$ apify create warehouse-watchdog --template=python-crawlee-beautifulsoup
	Info: Python version 0.0.0 detected.
	Info: Creating a virtual environment in ...
	...
	Success: Actor 'warehouse-watchdog' was created. To run it, run "cd warehouse-watchdog" and "apify run".
	Info: To run your code in the cloud, run "apify push" and deploy your code to Apify Console.
	Info: To install additional Python packages, you need to activate the virtual environment in the ".venv" folder in the actor directory.
	```
	Change to a directory where you start new projects in your terminal. Then, run the following command:
	`$ apify create warehouse-watchdog --template=python-crawlee-beautifulsoup`
	it will create a new subdirectory called `warehouse-watchdog` for the new project, containing all the necessary files:
	```text
	Info: Python version 0.0.0 detected.
	Info: Creating a virtual environment in ...
	...
	Success: Actor 'warehouse-watchdog' was created. To run it, run "cd warehouse-watchdog" and "apify run".
	Info: To run your code in the cloud, run "apify push" and deploy your code to Apify Console.
	Info: To install additional Python packages, you need to activate the virtual environment in the ".venv" folder in the actor directory.

[B4nan]

the images here are technically already a part of this git repo now

They are part of your branch only, which will be wiped after we merge.