You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: The official documentation for UserFrosting, a PHP framework and full-featured user management application.
4
-
obsolete: true
5
4
---
6
5
7
6
UserFrosting is a free, open-source jumping-off point for building user-centered web applications with PHP and Javascript. It comes with a sleek, modern interface, basic user account features, and an administrative user management system - all fully functioning out of the box.
@@ -10,49 +9,59 @@ UserFrosting is a free, open-source jumping-off point for building user-centered
10
9
> This quick start guide is aimed at experienced PHP developers who already have a development environment set up. If that's not your case, head over to the [First Chapter](background) to start your journey.
11
10
12
11
> [!IMPORTANT]
13
-
> This is the documentation for **UserFrosting 5**. If you are looking for documentation for _UserFrosting 4_, [click here](https://learn.userfrosting.com/4.6/).
12
+
> This is the documentation for **UserFrosting 6**. If you are looking for documentation for _UserFrosting 5_, [click here](https://learn.userfrosting.com/5.1/).
14
13
15
14
## Requirements
16
15
17
16
> [!TIP]
18
-
> Using Docker? [Check out the Docker Documentation](installation/environment/docker) to install UserFrosting through it's native Docker integration.
17
+
> Using Docker? [Check out the Docker Documentation](installation/environment/docker) to install UserFrosting through its native Docker integration.
19
18
20
19
UserFrosting has a few system requirements. You need to make sure your local UserFrosting development environment meets the following requirements:
21
20
22
-
- PHP **8.1 or higher** (*8.3* recommended)
21
+
- PHP **8.1 or higher** (*8.4* recommended)
23
22
-[Composer 2](https://getcomposer.org/)
24
-
-[Node.js](https://nodejs.org/en/)**18.0** or higher, and [npm](https://www.npmjs.com)**9.0** or higher
23
+
-[Node.js](https://nodejs.org/en/)**18.0** or higher (*24 LTS* recommended)
24
+
-[npm](https://www.npmjs.com)**9.0** or higher
25
25
26
26
## Installing UserFrosting
27
27
28
-
Use Composer to create an empty project with the latest version of UserFrosting skeleton into a new`UserFrosting` folder. This will clone the skeleton repository and run the installation process.
28
+
Use Composer to create a new project with the latest version of UserFrosting into a `UserFrosting` folder. This will clone the skeleton repository and run the installation process.
> During installation, you can choose **sqlite** as database provider if you don't have a database provider available.
35
+
> During installation, you can choose **SQLite** as the database provider if you don't have a database server available.
36
36
37
-
If any dependencies are not met, an error will occur. Simply try again after fixing said error, or manually run `composer install` and `php bakery bake` from the install directory. For more information about the `bake` command, head to the [Bakery CLI](cli) chapter.
37
+
If any dependencies are not met, an error will occur. Simply try again after fixing the error, or manually run `composer install` and `php bakery bake` from the installation directory. For more information about the `bake` command, see the [Bakery CLI](cli) chapter.
38
38
39
-
At this point you can run locally using the PHP Server :
39
+
At this point, you can run the application locally using the PHP and Vite development servers. First, change to the project directory:
40
40
41
41
```bash
42
42
cd UserFrosting
43
43
```
44
+
45
+
Now, in two separate terminals, run each server simultaneously:
46
+
47
+
*First Terminal:*
44
48
```bash
45
49
php bakery serve
46
50
```
47
51
48
-
You can now access UserFrosting at : [http://localhost:8080](http://localhost:8080)
52
+
*Second Terminal:*
53
+
```bash
54
+
npm run vite:dev
55
+
```
56
+
57
+
You can now access UserFrosting at: [http://localhost:8080](http://localhost:8080)
49
58
50
-
## Visit your website
59
+
## Visit Your Website
51
60
52
-
At this point, you should be able to access your application. You should see a basic page:
61
+
At this point, you should be able to access your application. You should see the default front page:
53
62
54
63
55
64
56
-
## What's next...
65
+
## What's Next
57
66
58
-
For more detailed information about installing UserFrosting, or if you need help with the basic setup requirements, check out the [Installation Chapter](installation). Otherwise, head over to the [Sprinkles Chapter](sprinkles).
67
+
For more detailed information about installing UserFrosting, or if you need help with the basic setup requirements, check out the [Installation Chapter](installation). Otherwise, head over to the [Sprinkles Chapter](sprinkles) to learn about UserFrosting's modular architecture.
Copy file name to clipboardExpand all lines: app/pages/6.0/04.installation/02.environment/02.docker/docs.md
+32-28Lines changed: 32 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,14 +4,15 @@ description: Docker is a containerization platform that helps maintain consisten
4
4
obsolete: true
5
5
---
6
6
7
-
If you don't already have a local environment or you're not familiar with **Docker**, this page will guide you in installing UserFrosting using Docker.
7
+
If you don't already have a local development environment set up, this page will guide you through installing UserFrosting using Docker.
8
8
9
-
Docker provides a great starting point for building a UserFrosting application using PHP, NGINX, and MySQL without requiring prior Docker experience. All the necessary tools will be available through Docker. The only necessary tool required on your computer, besides Docker, is the **command line**.
9
+
Docker provides a great starting point for building a UserFrosting application using PHP, NGINX, and MySQL without requiring prior Docker experience. All the necessary tools will be available through Docker. The only tool required on your computer, besides Docker, is access to the **command line**.
10
10
11
11
If you're familiar with PHP development, or already have PHP installed locally, you may instead want to consider setting up [natively](installation/environment/native).
@@ -25,7 +26,7 @@ First, you'll need to install Docker. Just follow the installation instructions
25
26
For the next part, you'll need to use the command line. We'll use Composer (through a Docker image) to create an empty project, with the latest version of the UserFrosting skeleton, into a new `UserFrosting` subdirectory:
@@ -42,56 +43,59 @@ Now it's simply a matter of navigating to the directory containing the source co
42
43
```
43
44
44
45
> [!TIP]
45
-
> If you customized `UserFrosting` in the previous command, don't forget to change it in the command above.
46
+
> If you customized `UserFrosting` in the previous command, don't forget to change it in the command above.
46
47
47
48
2. Build each of the Docker Containers (this might take a while):
48
49
49
50
```bash
50
51
docker-compose build --no-cache
51
52
```
52
53
53
-
3. Start each Docker Container:
54
+
3. Copy the `.env` template
55
+
```bash
56
+
cp app/.env.docker app/.env
57
+
```
58
+
59
+
4. Start each Docker Container:
54
60
55
61
```bash
56
62
docker-compose up -d
57
63
```
58
64
59
-
4. Set some directory permissions (your may have to enter your root password):
65
+
5. Set some directory permissions (you may have to enter your root password):
60
66
61
67
```bash
62
68
sudo touch app/logs/userfrosting.log
63
69
sudo chown -R $USER: .
64
70
sudo chmod 777 app/{logs,cache,sessions}
65
71
```
66
72
67
-
5. Install PHP dependencies:
73
+
6. Install PHP dependencies:
68
74
69
75
```bash
70
76
docker-compose exec app composer update
71
77
```
72
78
73
-
6. Install UserFrosting (database configuration and migrations, creation of admin user, etc.). You'll need to provide info to create the admin user:
79
+
7. Install UserFrosting (database configuration and migrations, creation of admin user, etc.). You'll need to provide info to create the admin user:
74
80
75
81
```bash
76
82
docker-compose exec app php bakery bake
77
83
```
78
84
79
85
Now visit [http://localhost:8080](http://localhost:8080) to see your UserFrosting homepage!
80
86
81
-
You should see the default UserFrosting pages and be able to login with the newly created master account.
87
+
You should see the default UserFrosting pages and be able to log in with the newly created admin account.
82
88
83
-
89
+
84
90
85
-
To stop the containers, run :
91
+
To stop the containers, run:
86
92
87
93
```bash
88
94
docker-compose stop
89
95
```
90
96
91
97
## Mailpit
92
98
93
-
You can see captured email at [http://localhost:8025](http://localhost:8025).
94
-
95
99
UserFrosting's default `docker-compose.yml` file contains a service entry for [Mailpit](https://github.com/axllent/mailpit). Mailpit intercepts emails sent by your application during local development and provides a convenient web interface so that you can preview your email messages in your browser.
96
100
97
101
While UserFrosting is running, you may access the Mailpit web interface at: [http://localhost:8025](http://localhost:8025).
If you need to stop the UserFrosting docker containers, just change to your userfrosting directory and run:
115
+
If you need to stop the UserFrosting Docker containers, change to your UserFrosting directory and run:
112
116
113
117
```bash
114
118
docker-compose stop
115
119
```
116
120
117
-
To start containers again, change to your userfrosting directory and run:
121
+
To start the containers again, change to your UserFrosting directory and run:
118
122
119
123
```bash
120
124
docker-compose up -d
121
125
```
122
126
123
-
If you need to purge your docker containers (this will not delete any source file or sprinkle, but will empty the database), run:
127
+
If you need to purge your Docker containers (this will not delete any source files or sprinkles, but will empty the database), run:
124
128
125
129
```bash
126
130
docker-compose down --remove-orphans
@@ -130,30 +134,30 @@ And then start the installation process again.
130
134
131
135
## Advanced configuration
132
136
133
-
At the heart of everything is the `docker-compose.yml` file. If you're experienced with Docker and Docker Compose, this is where you can customize your Docker experience. For example, you can customize the port each service runs on. And since the file is located in *your Sprinkle*, aka your app, it's possible to save this file in your repo.
137
+
At the heart of everything is the `docker-compose.yml` file. If you're experienced with Docker and Docker Compose, this is where you can customize your Docker experience. For example, you can customize the port each service runs on. Since the file is located in *your sprinkle* (your app), it's possible to save this file in your repository.
134
138
135
139
The `docker-compose.yml` file also contains the MySQL database and Mail environment variables. Since these variables are defined globally inside the container, they don't need to be redefined inside the `.env` file.
136
140
137
141
> [!WARNING]
138
-
> If you have **two** instances of UserFrosting on your computer, **they will share the same config**. This means a couple of things:
139
-
> 1. You can't run both Docker instances of UserFrosting *at the same time* with the default config, as ports will overlap.
142
+
> If you have **multiple** instances of UserFrosting on your computer, **they will share the same configuration by default**. This means:
143
+
> 1. You can't run multiple Docker instances of UserFrosting *simultaneously* with the default configuration, as ports will conflict.
140
144
> 2. Both instances will share the same database.
141
-
> If you wish to run multiple instances of UserFrosting on the same computer with Docker, you must edit the `docker-compose.yml` of all but one instance and change the default ports and database volumes/database names.
145
+
>
146
+
> If you wish to run multiple instances of UserFrosting on the same computer with Docker, you must edit the `docker-compose.yml` for each instance and change the ports and database volumes/database names.
142
147
143
148
> [!NOTE]
144
149
> An "*address already in use*" error can be thrown if a port defined in `docker-compose.yml` is already used on your system. For example, if Mailpit is installed locally and running on the default port, you'll get an "address already in use" error when running Docker. This can be solved by changing the port in `docker-compose.yml`.
145
150
146
-
## Production environment
151
+
## Production Environment
147
152
148
-
**This is not (yet) meant for production!**
153
+
**This setup is not (yet) meant for production!**
149
154
150
-
You may be tempted to run with this in production, but this setup has not been security-hardened. For example:
155
+
You may be tempted to use this configuration in production, but it has not been security-hardened. For example:
151
156
152
-
- The database is exposed on port 8593 so you can access MySQL using your favorite client at localhost:8593. However,
153
-
the way Docker exposes ports bypasses common firewalls like `ufw`. This should not be exposed in production.
154
-
- Database credentials are hard-coded — obviously not secure.
155
-
- File permissions may be more open than necessary.
157
+
- The database is exposed on port 8593 so you can access MySQL using your favorite client at `localhost:8593`. However, the way Docker exposes ports bypasses common firewalls like `ufw`. This should not be exposed in production.
158
+
- Database credentials are hard-coded, which is not secure.
159
+
- File permissions may be more permissive than necessary.
156
160
- HTTPS is not implemented.
157
-
-It just hasn't been thoroughly tested in the capacity of being a production system.
161
+
-This setup has not been thoroughly tested as a production system.
158
162
159
163
If you're experienced with Docker in a production environment, don't hesitate to reach out and contribute to this documentation.
0 commit comments