|
| 1 | +# Start a Laravel Octane Project with Docker in 3 Easy Steps |
| 2 | + |
| 3 | +1. Run `kool create laravel+octane my-project` |
| 4 | +2. Update **.env.example** |
| 5 | +3. Run `kool run setup` |
| 6 | + |
| 7 | +> Yes, using **kool** + Docker to create and work on new Laravel Octane projects is that easy! |
| 8 | +
|
| 9 | +## Requirements |
| 10 | + |
| 11 | +If you haven't done so already, you first need to [install Docker and the kool CLI](/docs/getting-started/installation). |
| 12 | + |
| 13 | +Also, make sure you're running the latest version of **kool**. Run the following command to compare your local version of **kool** with the latest release, and, if a newer version is available, automatically download and install it. |
| 14 | + |
| 15 | +```bash |
| 16 | +$ kool self-update |
| 17 | +``` |
| 18 | + |
| 19 | +> Please note that it helps to have a basic understanding of how Docker and Docker Compose work to use Kool with Docker. |
| 20 | +
|
| 21 | +## 1. Run `kool create laravel+octane my-project` |
| 22 | + |
| 23 | +Use the [`kool create PRESET FOLDER` command](/docs/commands/kool-create) to create your new Laravel Octane project: |
| 24 | + |
| 25 | +```bash |
| 26 | +$ kool create laravel+octane my-project |
| 27 | +``` |
| 28 | + |
| 29 | +Under the hood, this command will run do the same as the standar Laravel preset to get a fresh install of latest Laravel using a customized **kool** Docker image with Swoole: <a href="https://github.com/kool-dev/docker-php-swoole" target="_blank">kooldev/php:8.1-nginx-swoole</a>. |
| 30 | + |
| 31 | +After installing Laravel, `kool create` automatically requires `laravel/octane` and runs `artisan octane:install`. After that you will have the options for including a database or cache service, all of which helps you easily set up the initial tech stack for your project using an interactive wizard. |
| 32 | + |
| 33 | +--- |
| 34 | + |
| 35 | +Now, move into your new Laravel Octane with Swoole project: |
| 36 | + |
| 37 | +```bash |
| 38 | +$ cd my-project |
| 39 | +``` |
| 40 | + |
| 41 | +The [`kool preset` command](/docs/commands/kool-preset) auto-generated the following configuration files and added them to your project, which you can modify and extend. |
| 42 | + |
| 43 | +```bash |
| 44 | ++docker-compose.yml |
| 45 | ++kool.yml |
| 46 | +``` |
| 47 | + |
| 48 | +> Now's a good time to review the **docker-compose.yml** file and verify the services match the choices you made earlier using the wizard. |
| 49 | +
|
| 50 | +## 2. Update .env.example |
| 51 | + |
| 52 | +You need to update some default values in Laravel's **.env.example** file to match the services in your **docker-compose.yml** file. |
| 53 | + |
| 54 | +### Database Services |
| 55 | + |
| 56 | +MySQL 5.7 and 8.0 or MariaDB 10.5 |
| 57 | + |
| 58 | +```diff |
| 59 | +-DB_HOST=127.0.0.1 |
| 60 | ++DB_HOST=database |
| 61 | +``` |
| 62 | + |
| 63 | +PostgreSQL 13.0 |
| 64 | + |
| 65 | +```diff |
| 66 | +-DB_CONNECTION=mysql |
| 67 | ++DB_CONNECTION=pgsql |
| 68 | + |
| 69 | +-DB_HOST=127.0.0.1 |
| 70 | ++DB_HOST=database |
| 71 | + |
| 72 | +-DB_PORT=3306 |
| 73 | ++DB_PORT=5432 |
| 74 | +``` |
| 75 | + |
| 76 | +> In order to avoid permission issues with mysql and mariaDB, add a user other than root and a password to your **.env.example** file |
| 77 | +
|
| 78 | +```diff |
| 79 | +-DB_USERNAME=root |
| 80 | ++DB_USERNAME=<some_user> |
| 81 | + |
| 82 | +-DB_PASSWORD= |
| 83 | ++DB_PASSWORD=<somepass> |
| 84 | +``` |
| 85 | + |
| 86 | +### Cache Services |
| 87 | + |
| 88 | +Redis |
| 89 | + |
| 90 | +```diff |
| 91 | +-REDIS_HOST=127.0.0.1 |
| 92 | ++REDIS_HOST=cache |
| 93 | +``` |
| 94 | + |
| 95 | +Memcached |
| 96 | + |
| 97 | +```diff |
| 98 | +-MEMCACHED_HOST=127.0.0.1 |
| 99 | ++MEMCACHED_HOST=cache |
| 100 | +``` |
| 101 | + |
| 102 | +## 3. Run `kool run setup` |
| 103 | + |
| 104 | +> Say hello to **kool.yml**, say goodbye to custom shell scripts! |
| 105 | +
|
| 106 | +As mentioned above, the [`kool preset` command](/docs/commands/kool-preset) added a **kool.yml** file to your project. Think of **kool.yml** as a super easy-to-use task _helper_. Instead of writing custom shell scripts, add your own scripts to **kool.yml** (under the `scripts` key), and run them with `kool run SCRIPT` (e.g. `kool run artisan`). You can add your own single line commands (see `composer` below), or add a list of commands that will be executed in sequence (see `setup` below). |
| 107 | + |
| 108 | +To help get you started, **kool.yml** comes prebuilt with an initial set of scripts (based on the choices you made earlier using the **preset** wizard), including a script called `setup`, which helps you spin up a project for the first time. |
| 109 | + |
| 110 | +```yaml |
| 111 | +scripts: |
| 112 | + artisan: kool exec app php artisan |
| 113 | + composer: kool exec app composer |
| 114 | + mysql: kool exec -e MYSQL_PWD=$DB_PASSWORD database mysql -uroot |
| 115 | + node: kool docker kooldev/node:16 node |
| 116 | + npm: kool docker kooldev/node:16 npm # or yarn |
| 117 | + npx: kool exec app npx |
| 118 | + |
| 119 | + setup: |
| 120 | + - kool run before-start |
| 121 | + - kool start |
| 122 | + - kool run composer install |
| 123 | + - kool run artisan key:generate |
| 124 | + |
| 125 | + reset: |
| 126 | + - kool run composer install |
| 127 | + - kool run artisan migrate:fresh --seed |
| 128 | + - kool run yarn install |
| 129 | + |
| 130 | + before-start: |
| 131 | + - kool docker kooldev/bash -c "cp .env.example .env" |
| 132 | + - kool run yarn install |
| 133 | +``` |
| 134 | +
|
| 135 | +Go ahead and run `kool run setup` to start your Docker environment and finish setting up your project: |
| 136 | + |
| 137 | +```bash |
| 138 | +# CAUTION: this script will reset your `.env` file with `.env.example` |
| 139 | +$ kool run setup |
| 140 | +``` |
| 141 | + |
| 142 | +> As you can see in **kool.yml**, the `setup` script will do the following in sequence: copy your updated **.env.example** file to **.env**; start your Docker environment; use Composer to install vendor dependencies; generate your `APP_KEY` (in `.env`); and then build your Node packages and assets. |
| 143 | +
|
| 144 | +Once `kool run setup` finishes, you should be able to access your new site at [http://localhost](http://localhost) and see the Laravel welcome page. Hooray! |
| 145 | + |
| 146 | +Verify your Docker container is running using the [`kool status` command](/docs/commands/kool-status). |
| 147 | + |
| 148 | +Run `kool logs app` to see the logs from the running `app` container. |
| 149 | + |
| 150 | +> Use `kool logs` to see the logs from all running containers. Add the `-f` option after `kool logs` to follow the logs (i.e. `kool logs -f app`). |
| 151 | +
|
| 152 | +--- |
| 153 | + |
| 154 | +### Run Commands in Docker Containers |
| 155 | + |
| 156 | +Use [`kool exec`](/docs/commands/kool-exec) to execute a command inside a running service container: |
| 157 | + |
| 158 | +```bash |
| 159 | +# kool exec [OPTIONS] SERVICE COMMAND [--] [ARG...] |
| 160 | + |
| 161 | +$ kool exec app ls |
| 162 | +``` |
| 163 | + |
| 164 | +Try `kool run artisan --help` to execute the `kool exec app php artisan --help` command in your running `app` container and print out information about Laravel's CLI commands. |
| 165 | + |
| 166 | +### Open Sessions in Docker Containers |
| 167 | + |
| 168 | +Similar to SSH, if you want to open a Bash session in your `app` container, run `kool exec app bash`, where `app` is the name of the service container in **docker-compose.yml**. If you prefer, you can use `sh` instead of `bash` (`kool exec app sh`). |
| 169 | + |
| 170 | +```bash |
| 171 | +$ kool exec app bash |
| 172 | +bash-5.1# |
| 173 | + |
| 174 | +$ kool exec app sh |
| 175 | +/app # |
| 176 | +``` |
| 177 | + |
| 178 | +### Connect to Docker Database Container |
| 179 | + |
| 180 | +You can easily start a new SQL client session inside your running `database` container by executing `kool run mysql` (MySQL) or `kool run psql` (PostgreSQL) in your terminal. This runs the single-line `mysql` or `psql` script included in your **kool.yml**. |
| 181 | + |
| 182 | +### Access Private Repos and Packages in Docker Containers |
| 183 | + |
| 184 | +If you need your `app` container to use your local SSH keys to pull private repositories and/or install private packages (which have been added as dependencies in your `composer.json` or `package.json` file), you can simply add `$HOME/.ssh:/home/kool/.ssh:delegated` under the `volumes` key of the `app` service in your **docker-compose.yml** file. This maps a `.ssh` folder in the container to the `.ssh` folder on your host machine. |
| 185 | + |
| 186 | +```diff |
| 187 | +volumes: |
| 188 | + - .:/app:delegated |
| 189 | ++ - $HOME/.ssh:/home/kool/.ssh:delegated |
| 190 | +``` |
| 191 | + |
| 192 | +## Staying kool |
| 193 | + |
| 194 | +When it's time to stop working on the project: |
| 195 | + |
| 196 | +```bash |
| 197 | +$ kool stop |
| 198 | +``` |
| 199 | + |
| 200 | +And when you're ready to start work again: |
| 201 | + |
| 202 | +```bash |
| 203 | +$ kool start |
| 204 | +``` |
| 205 | + |
| 206 | +## Additional Presets |
| 207 | + |
| 208 | +We have more presets to help you start projects with **kool** in a standardized way across different frameworks. |
| 209 | + |
| 210 | +- **[AdonisJs](/docs/2-Presets/AdonisJs.md)** |
| 211 | +- **[CodeIgniter](/docs/2-Presets/CodeIgniter.md)** |
| 212 | +- **[Express.js](/docs/2-Presets/ExpressJS.md)** |
| 213 | +- **[Hugo](/docs/2-Presets/Hugo.md)** |
| 214 | +- **[NestJS](/docs/2-Presets/NestJS.md)** |
| 215 | +- **[Next.js](/docs/2-Presets/NextJS.md)** |
| 216 | +- **[Node.js](/docs/2-Presets/NodeJS.md)** |
| 217 | +- **[Nuxt.js](/docs/2-Presets/NuxtJS.md)** |
| 218 | +- **[PHP](/docs/2-Presets/PHP.md)** |
| 219 | +- **[Symfony](/docs/2-Presets/Symfony.md)** |
| 220 | +- **[WordPress](/docs/2-Presets/WordPress.md)** |
| 221 | + |
| 222 | +Missing a preset? **[Make a request](https://github.com/kool-dev/kool/issues/new)**, or contribute by opening a Pull Request. Go to [https://github.com/kool-dev/kool/tree/main/presets](https://github.com/kool-dev/kool/tree/main/presets) and browse the code to learn more about how presets work. |
0 commit comments