Skip to content

Commit f178622

Browse files
mychidarkomychidarko
committed
feat: add codelabs
1 parent 972c9d0 commit f178622

File tree

5 files changed

+321
-1
lines changed

5 files changed

+321
-1
lines changed

‎src/codelabs/experiments/deployment/digitalocean/index.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
sidebar: false
3+
editLink: false
4+
prev: false
5+
next: false
6+
lastUpdated: false
7+
---
8+
9+
# Deploying a LeafMVC Application to Digital Ocean
10+
11+
::: warning Version support
12+
Version support. This tutorial assumes use of LeafPHP >= 3.0 and PHP >=7.0.
13+
:::
14+
15+
## What Are We Building
16+
17+
This experiment will guide you deploying your first LeafMVC application to Digital Ocean. A majority
18+
of the same steps apply to Leaf v3 core as well.
19+
20+
::: details (New to Digital Ocean?)
21+
Digital Ocean is a cloud service provider that offers great introductory pricing for virtual private
22+
servers (VPS). Create an account, tether a credit card, and prepare to build.
23+
:::
24+
25+
## Prerequisites
26+
27+
Before continuing, it is important to determine if you would like to purhcase or point a domain name
28+
to the VPS you are about to spin up. $DOMAIN will be shown several times throughout this experiment
29+
and should be replaced by either your domain name (example.com) or the Droplet's public IP address. You
30+
can grab the public IP address from the Digital Ocean control panel.
31+
32+
For instructions on how to setup a domain with Digital Ocean, [click here](https://docs.digitalocean.com/products/networking/dns/how-to/add-domains/).
33+
34+
## 1. Create a new droplet
35+
36+
From the control panel, click the green "Create" button and select droplet. We will create a VPS with the
37+
following options selected:
38+
39+
* Ubuntu: 20.04 (LTS)
40+
* Plan: Basic
41+
* CPU Options: Premium AMD or Regular Intel
42+
* $6/mo package
43+
44+
::: tip Scaling ⚡️
45+
Should your application grow in requirements or traffic, you can always come back and increase your package selection.
46+
:::
47+
48+
### Authentication
49+
50+
It is highly recommended that your utilize SSH-based authentication. Select an existing key, or [generate a new key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent), then add it.
51+
52+
## 2. Initial droplet setup
53+
54+
After your droplet has been created, you will need to login, secure it, and install required software. The first task will
55+
be to create an admin user, then utilie that account for future SSH connections.
56+
57+
```bash
58+
ssh root@$DOMAIN
59+
adduser username
60+
usermod -aG sudo username
61+
rsync --archive --chown=username:username ~/.ssh /home/username
62+
```
63+
64+
Test the admin account: ``su - username``. If the command executes, you can terminal the SSH session and log
65+
back in with your new user account (recommended).
66+
67+
### Setup firewall
68+
69+
Next we will setup UFW - Ubuntu Firewall. We will allow communication on ports: 22 (SSH), 80 (HTTP), and 443 (SSL).
70+
71+
```bash
72+
sudo ufw allow 22
73+
sudo ufw allow 80
74+
sudo ufw allow 443
75+
sudo ufw enable
76+
```
77+
78+
After creating the firewall's rules and enabling UFW, you can view firewall status by ``sudo ufw status``.
79+
80+
### Install required software
81+
82+
It is now time install all of the needed software to enable LeafPHP to run. First, we need to update all system software:
83+
84+
```bash
85+
sudo apt update
86+
sudo apt upgrade
87+
```
88+
89+
Be sure to respond **Y** when asked to continue. Now we can intall NGINX, PHP, MySQL, and curl.
90+
91+
```bash
92+
sudo apt install nginx php-fpm php-mysql php-curl
93+
```
94+
95+
Once complete, follow the
96+
[NGINX instructions](https://www.digitalocean.com/community/tutorials/how-to-install-linux-nginx-mysql-php-lemp-stack-ubuntu-18-04#step-3-%E2%80%93-installing-php-and-configuring-nginx-to-use-the-php-processor).
97+
Ensure that your directory is set as such: `` root /var/www/$DOMAIN/public;`` Below is an example sites-available file.
98+
99+
```nginx
100+
server {
101+
server_name itsglint.com www.itsglint.com 147.182.136.153;
102+
root /var/www/itsglint.com/public;
103+
104+
index index.html index.htm index.php;
105+
106+
location / {
107+
try_files $uri /index.php?$query_string;
108+
}
109+
110+
location ~ \.php$ {
111+
include snippets/fastcgi-php.conf;
112+
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
113+
}
114+
}
115+
```
116+
117+
::: warning Leaf Router and .htaccess support
118+
It is important to mirror the location blocks as-in. Otherwise, LeafRouter will not work properly or at all.
119+
:::
120+
121+
Next, we will install Mysql. Follow the [install instructions](https://www.digitalocean.com/community/tutorials/how-to-install-linux-nginx-mysql-php-lemp-stack-ubuntu-18-04#step-2-%E2%80%93-installing-mysql-to-manage-site-data).
122+
123+
```bash
124+
sudo apt install mysql-server
125+
```
126+
127+
### Install your Leaf🍁 application
128+
129+
Next, we will download and install our application with all dependencies. Clone your repository from Github,
130+
or any source, and place your Leaf project in ``/var/www/$DOMAIN``. Afterwards, install required dependencies
131+
and perform initial Leaf tasks:
132+
133+
```bash
134+
composer install
135+
php leaf db:install
136+
php leaf db:migrate
137+
```
138+
139+
You also may seed the database if required: `php leaf db:seed`.
140+
141+
Congratulations 🎉, you now have a fully working production server, and should be able to reach your application at $DOMAIN.
142+
143+
::: details Recommended: Complete SSL Setup
144+
If your Leaf applications is more than a hobbyist adventure and serving actual clients or visitors, it is
145+
strongly recommended to complete the SSL setup. SSL encrypts traffic between a browser and server. Replace
146+
example.com with $DOMAIN.
147+
148+
```
149+
sudo apt install certbot python3-certbot-nginx
150+
sudo systemctl reload nginx
151+
sudo certbot --nginx -d example.com -d www.example.com
152+
```
153+
154+
When prompted for HTTPS redirction, select **Option 2**, forcing HTTPS traffic.
155+
156+
:::
157+
158+
<br>
159+
160+
Experiment by **[Matthew Reichardt](https://github.com/matthewjamesr)**

‎src/codelabs/experiments/deployment/fly.io/index.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Deploying a LeafMVC Application to Fly.io
2+
3+
::: warning Version support
4+
Version support. This tutorial assumes use of LeafPHP >= 3.0 and PHP >=7.0.
5+
:::
6+
7+
## What Are We Building
8+
9+
This experiment will guide you deploying your first LeafMVC / base Leaf application to Fly.io. A majority
10+
of the same steps apply to Leaf v3 core as well. This guide uses docker to deploy your application.
11+
You do not need to have docker installed on your local machine to follow this guide. Neither do you
12+
need to have prior knowledge of docker.
13+
14+
::: details (New to Fly.io?)
15+
Fly.io transforms containers into micro-VMs that run on their hardware.
16+
:::
17+
18+
## Prerequisites
19+
20+
This tutorial assumes you have the following:
21+
22+
- A Leaf application
23+
- A Fly.io account
24+
- The [flyctl cli tool](https://fly.io/docs/hands-on/install-flyctl/) installed
25+
26+
## 1. Set up docker in your Leaf application
27+
28+
You can clone the [Fly.io starter template](https://github.com/cr34t1ve/leaf-fly-io-template) to get started.
29+
30+
```bash
31+
git clone https://github.com/cr34t1ve/leaf-fly-io-template.git
32+
```
33+
34+
This template has a `Dockerfile` and a `fly.toml` file already set up for you.
35+
36+
## 2. Deploy your application
37+
38+
Navigate to your application's root directory and run the following command:
39+
40+
```bash
41+
fly deploy
42+
```
43+
44+
This command will build your docker image and deploy it to Fly.io.
45+
46+
After setting up your application, you can then run the following to launch your application:
47+
48+
```bash
49+
fly launch
50+
```
51+
52+
You can then visit your application at the URL provided.
53+
54+
## Conclusion
55+
56+
You have successfully deployed your LeafMVC application to Fly.io. You can now scale your application
57+
58+
Experiment by **[Desmond Sofua](https://github.com/cr34t1ve)**

‎src/codelabs/experiments/deployment/heroku/index.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Deploying a Leaf Application to Heroku
2+
3+
::: warning Version support
4+
Version support. This tutorial assumes use of Leaf CLI >= 2.2.0 (🍊 Yomi Yomi no Mi).
5+
:::
6+
7+
## What Are We Building?
8+
9+
This experiment will guide you deploying your first Leaf application to Heroku. The same steps apply to Leaf MVC, Leaf API and Skeleton.
10+
11+
::: details (New to Heroku?)
12+
Heroku is a platform as a service (PaaS) that enables developers to build, run, and operate applications entirely in the cloud. Create an account, tether a credit card, and prepare to build.
13+
:::
14+
15+
## Prerequisites
16+
17+
This tutorial assumes you have the following:
18+
19+
- A Leaf application
20+
- A Heroku account
21+
- The Heroku CLI installed
22+
23+
## 1. Create a new heroku app
24+
25+
From the dashboard, select create new app. Give your app a name, and select a region. The region should be the closest to your location.
26+
27+
<img width="810" alt="image" src="https://github.com/leafsphp/leaf/assets/26604242/f189892d-9164-4c1a-b396-b3b50066f118" style="border-radius: 10px;">
28+
29+
**Note that per Heroku's new terms, you should have a payment method connected.**
30+
31+
Clicking on create app, should take you to an empty new app page. From here, you can select the deploy tab, and connect your Github repository.
32+
33+
<img width="1262" alt="image" src="https://github.com/leafsphp/leaf/assets/26604242/89356d46-0b46-46e6-9659-e77bc9f2f03d" style="border-radius: 10px;">
34+
35+
## 2. Initializing your app
36+
37+
For most use-cases, you would usually push your project to GitHub, then connect your repository to Heroku. However, for this experiment, we will be pushing your app to Heroku directly using the Leaf CLI.
38+
39+
To get started, you will need to make sure you are logged in to Heroku. You can do this by running `heroku login`. You will be prompted to login in your browser. Once you have logged in, you can proceed.
40+
41+
Heroku uses git to deploy your application, so you will need to initialize git in your repository. You can do this by running `git init` in your project directory. After initializing git, you can add your files to the staging area by running `git add .`. Once you have added your files, you can commit them by running `git commit -m "commit message"`.
42+
43+
## 3. Deploying your app
44+
45+
Now for the interesting part. We can deploy our application using Leaf CLI's `deploy` command.
46+
47+
```bash
48+
leaf deploy --to heroku --project your-project-name
49+
```
50+
51+
For this example, our command would look like this:
52+
53+
```bash
54+
leaf deploy --to heroku --project leafcodelabs
55+
```
56+
57+
This command will setup the Heroku remote, build your app and push it to your Heroku project. Once the command is complete, you should see your deploy in the `Deploys` tab on the heroku dashboard.
58+
59+
<br>
60+
61+
Experiment by **[Michael Darko](https://github.com/mychidarko)**

‎src/codelabs/experiments/deployment/index.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Deployment
2+
3+
This is a collection of codelab experiments related to deployment across different platforms.
4+
5+
| Provider | Description |
6+
| :-------------------------------------------------------------- | :--------------------------------------------------------- |
7+
| [Digital Ocean](/codelabs/experiments/deployment/digitalocean/) | Deploying LeafMVC projects to a new Digital Ocean droplet |
8+
| [Heroku](/codelabs/experiments/deployment/heroku/) | Deploying a base Leaf project to Heroku using the Leaf CLI |
9+
| [Fly.io](/codelabs/experiments/deployment/fly.io/) | Deploying a base Leaf application to Fly.io |

‎src/codelabs/index.md‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,33 @@
1-
# Code labs
1+
---
2+
sidebar: false
3+
editLink: false
4+
prev: false
5+
next: false
6+
lastUpdated: false
7+
---
8+
9+
# Leaf Codelabs
10+
11+
We created Codelabs to give you interactive step-by-step real-world tutorials on Leaf, PHP and JS concepts that help you achieve specific results in your apps. Codelabs takes one topic or "how-to" and dives deep into it, giving you all the information you need to successfully complete the tutorial yourself while also explaining useful concepts along the way.
12+
13+
## Codelabs vs the Docs
14+
15+
Codelabs are hands-on, standalone tutorials focused on specific Leaf features, unlike our docs, which follow a story-like flow. They dive deeper with complex examples that combine features in interesting ways that may not be fully covered in the docs.
16+
17+
While our documentation is beginner-friendly, we only have the space to cover PHP and general web concepts. Codelabs on the other hand will explain any concepts that are essential to that specific tutorial, eg: "how to update your Leaf app on DigitalOcean" will explain DigitalOcean, SSH, and Linux concepts necessary to complete the tutorial.
18+
19+
## Experiments
20+
21+
We call a tutorial in Codelabs an "experiment". Each experiment is a standalone tutorial that focuses on a particular topic. It is interactive and in-depth, covering what is needed in full.
22+
23+
Below is a list of all experiments:
24+
25+
| Topic | Description | Author |
26+
| :------------------------------------------------------ | :------------------------------------------------------------- | :----- |
27+
| [Deploying Leaf MVC to Digital Ocean](/codelabs/experiments/deployment/digitalocean/) | Deploying LeafMVC projects to a new Digital Ocean droplet | [Matthew Reichardt](https://github.com/matthewjamesr) |
28+
29+
***This list is still being updated.***
30+
31+
## Contributing
32+
33+
If you've written a tutorial that you think would be a great addition to our Codelabs, feel free to submit a PR to our [GitHub repository](https://github.com/leafsphp/docs) with your tutorial. For our readers' benefit, be sure to follow the [contribution guide](/codelabs/contributing) when submitting your tutorial. Thank you for your contribution!

0 commit comments

Comments
 (0)