Skip to content

Commit 3edf1a2

Browse files
perappuperappu
authored
feat(guides): add windows setup guide, restructure setup guides (#19)
* feat(guides): add first draft of windows local setup guide * feat(guides): combine local/dev environment sections, polish XAMPP guide * feat(guides): add barebones SSH client guide with windows information * feat(guides): split guides into software setup and development environment setup * feat(guides): update placeholder links for laragon and valet * feat(guides): add more clarification to software-windows and dev-windows guides based on feedback * feat(guides): alt text for the software-windows guide * feat(guides): switch windows guide to use sourcegit instead * fix(guides): remove remaining mentions of git extensions * feat(guides): recommended tweaks to windows local guides
1 parent fcf2745 commit 3edf1a2

File tree

101 files changed

+811
-19
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

101 files changed

+811
-19
lines changed

‎docs/guides/dev-setup/dev-windows.md‎

Lines changed: 369 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,369 @@
1+
# Local Development Setup - Windows
2+
3+
## Overview
4+
5+
- **This guide assumes you are on Windows.** [Mac](dev-setup/mac.md) and [Linux](dev-setup/linux.md) have different methods.
6+
- **Please read every step of this guide carefully.** It is highly recommend doing a full read-through before you even get started.
7+
8+
Within this guide, we will be installing the following software:
9+
10+
- [Composer](https://getcomposer.org) for handling PHP packages
11+
- [VS Code](https://code.visualstudio.com) as our code editor
12+
13+
!!! info "Windows Firewall Pop-ups"
14+
At any point in time while installing the below software, you may see a pop-up like this. **Click "Allow" to allow the software to finish installing.** All of the recommended software is safe.
15+
16+
<figure markdown="span">
17+
![Windows Firewall pop-up](../../images/software-setup/windows/xampp-firewall.png){ width="600" }
18+
</figure>
19+
20+
## Copying Lorekeeper
21+
22+
We are now going to use SourceGit to make a copy of Lorekeeper. This will be your personalized version that is posted to your live website.
23+
24+
1. In SourceGit, select the little cloud icon in the top right to "Clone Repository." "Clone" is the Git term for making a copy of the code.
25+
26+
<figure markdown="span">
27+
![clicking clone repository button in sourcegit](../../images/dev-setup/windows/cloning-lk-1.png){ width="600" }
28+
</figure>
29+
30+
2. Now we will fill out this field with some information that tells SourceGit where the Lorekeeper code is located. In the browser, it can be accessed [here](https://github.com/lk-arpg/lorekeeper), but we use a slightly different URL address when pasting it into Git.
31+
32+
- For **Repository URL**, paste in `https://github.com/lk-arpg/lorekeeper.git`.
33+
- For **Parent Folder**, this will define where the code exists on our computer. If you installed XAMPP in the directory `C:/xampp/`, we will be selecting the folder `C:/xampp/htdocs`. **If this folder does not exist, create it.**
34+
- Everything else can be left blank.
35+
36+
3. Your window should look like this:
37+
38+
<figure markdown="span">
39+
![filling in the clone repository form](../../images/dev-setup/windows/cloning-lk-2.png){ width="600" }
40+
</figure>
41+
42+
4. Click "OK" to beginning cloning, and the process will begin.
43+
44+
<figure markdown="span">
45+
![repository cloning in progress](../../images/dev-setup/windows/cloning-lk-3.png){ width="600" }
46+
</figure>
47+
48+
5. You now have a copy of Lorekeeper on your computer! The first thing you will want to do is rename the origin (core Lorekeeper) remote. Click the dropdown for "Remotes", and then right click "origin" and click "Edit".
49+
50+
<figure markdown="span">
51+
![repository cloning in progress](../../images/dev-setup/windows/cloning-lk-4.png){ width="600" }
52+
</figure>
53+
54+
6. Rename this branch to "lorekeeper", or another similar identifier that will indicate to you that this is where LK updates will come from.
55+
56+
<figure markdown="span">
57+
![repository cloning in progress](../../images/dev-setup/windows/cloning-lk-5.png){ width="600" }
58+
</figure>
59+
60+
7. Click "OK" to save the change. It should now look like this:
61+
62+
<figure markdown="span">
63+
![repository cloning in progress](../../images/dev-setup/windows/cloning-lk-6.png){ width="600" }
64+
</figure>
65+
66+
!!! info "Cloning a Higher Version of LK"
67+
68+
As of this writing, the main branch of LK is on version 2.1. You may wish to be on a higher version, such as the release branch version 3.0.
69+
70+
**Please note that is *extremely discouraged* to put your site on the develop branch of Lorekeeper.** Please see our [dev intro](../dev-intro#navigating-branches) regarding different branches.
71+
72+
SourceGit will clone the main branch by default. If you wish to update to version 3.0 or otherwise the current release, branch, simply pull that branch into your local branch with right click -> "Merge into main".
73+
74+
<figure markdown="span">
75+
![merging version 3 into main](../../images/dev-setup/windows/cloning-lk-higher-version.png){ width="600" }
76+
</figure>
77+
78+
## Setting Up Lorekeeper
79+
80+
We need to install two more pieces of software before we can get our copy of Lorekeeper fully up and running.
81+
82+
### Installing Composer
83+
84+
1. First, we will install Composer, which handles installation of PHP packages. Go [here](https://getcomposer.org) and select "Download".
85+
86+
<figure markdown="span">
87+
![alt text](../../images/dev-setup/windows/composer-1.png){ width="600" }
88+
</figure>
89+
90+
2. Click the link for the Windows Installer, then run it.
91+
92+
<figure markdown="span">
93+
![alt text](../../images/dev-setup/windows/composer-2.png){ width="600" }
94+
</figure>
95+
96+
3. Click to install for all users.
97+
98+
<figure markdown="span">
99+
![alt text](../../images/dev-setup/windows/composer-3.png){ width="600" }
100+
</figure>
101+
102+
4. Leave developer mode **unchecked**. Click "Next".
103+
104+
<figure markdown="span">
105+
![alt text](../../images/dev-setup/windows/composer-4.png){ width="600" }
106+
</figure>
107+
108+
5. XAMPP should be automatically selected as your command line version of PHP. If not, use the dropdown to select it. If prompted, also select the checkmark to add it to your path.
109+
110+
<figure markdown="span">
111+
![alt text](../../images/dev-setup/windows/composer-5.png){ width="600" }
112+
</figure>
113+
114+
6. Click "Next" on this screen.
115+
116+
<figure markdown="span">
117+
![alt text](../../images/dev-setup/windows/composer-6.png){ width="600" }
118+
</figure>
119+
120+
7. You will see a screen similar to this one, summarizing your options. Click "Install".
121+
122+
<figure markdown="span">
123+
![alt text](../../images/dev-setup/windows/composer-7.png){ width="600" }
124+
</figure>
125+
126+
8. On this screen, click "Next".
127+
128+
<figure markdown="span">
129+
![alt text](../../images/dev-setup/windows/composer-8.png){ width="600" }
130+
</figure>
131+
132+
9. Then, click "Finish"!
133+
134+
<figure markdown="span">
135+
![alt text](../../images/dev-setup/windows/composer-9.png){ width="600" }
136+
</figure>
137+
138+
10. **Reboot your computer.** While Composer mentions that it won't always be necessary, rebooting our computer after installing Composer is the best way to prevent issues.
139+
140+
### Installing Visual Studio Code
141+
142+
Visual Studio Code is the code editor we will use to edit our Lorekeeper files.
143+
144+
!!! info "A Note for Advanced Users"
145+
146+
You can install the VSCodium open source version, which comes with AI/Copilot features disabled by default, [here](https://github.com/VSCodium/vscodium/releases). However, you may run into issues with using certain extensions due to Microsoft's licensing.
147+
148+
1. Go [here](https://code.visualstudio.com) to download it and press the big download button. (Fortunately, we can disable the recently added AI features.)
149+
150+
<figure markdown="span">
151+
![alt text](../../images/dev-setup/windows/vscode-1.png){ width="600" }
152+
</figure>
153+
154+
2. Run the newly downloaded file. You will be presented with the license agreement. Check the agree button, then click "Next".
155+
156+
3. Check all the boxes (with desktop icon checked depending on your preference) and click "Next".
157+
158+
<figure markdown="span">
159+
![alt text](../../images/dev-setup/windows/vscode-2.png){ width="600" }
160+
</figure>
161+
162+
4. Click "Install".
163+
164+
5. It will then install. Check the button to launch it, then click the "Finish" button when complete.
165+
166+
<figure markdown="span">
167+
![alt text](../../images/dev-setup/windows/vscode-3.png){ width="600" }
168+
</figure>
169+
170+
!!! info "Disabling AI Features"
171+
Microsoft constantly changes how to disable AI features within Visual Studio Code. As a result, unfortunately we can not provide up-to-date instructions. Please use your favorite search engine to find the latest way to disable these features.
172+
173+
The Lorekeeper community does **not** encourage, promote, or endorse usage of AI tools.
174+
175+
## Running Lorekeeper
176+
177+
1. Open up the File Explorer and navigate to where Lorekeeper is installed on your computer. This is likely to be `C:/xampp/htdocs/lorekeeper` if you've been following our guides.
178+
179+
2. Right click anywhere in the empty space (make sure you don't have a file/directory selected!) and click "Open With Code".
180+
181+
<figure markdown="span">
182+
![alt text](../../images/dev-setup/windows/running-lk-2.png){ width="600" }
183+
</figure>
184+
185+
3. Behold! All of the files that make up your Lorekeeper. However, we need to install a few files before it will work properly. In the top bar, click "Terminal" and then "New Terminal".
186+
187+
<figure markdown="span">
188+
![alt text](../../images/dev-setup/windows/running-lk-3.png){ width="600" }
189+
</figure>
190+
191+
4. Type in `composer install`. A lot of text will go flying by as composer installs the various chunks of code required for LK to run.
192+
193+
<figure markdown="span">
194+
![alt text](../../images/dev-setup/windows/running-lk-4.png){ width="600" }
195+
</figure>
196+
197+
**It may get stuck for a while on `Generating optimized autoload files`. Be patient! It will finish eventually.**
198+
199+
<figure markdown="span">
200+
![alt text](../../images/dev-setup/windows/running-lk-5.png){ width="600" }
201+
</figure>
202+
203+
It should look like this when done:
204+
205+
<figure markdown="span">
206+
![alt text](../../images/dev-setup/windows/running-lk-6.png){ width="600" }
207+
</figure>
208+
209+
5. Next, we will create the .env file, which will define some variables that Lorekeeper needs to run. Right-click near the bottom of the file list and click "New File". Name this file `.env`.
210+
211+
<figure markdown="span">
212+
![alt text](../../images/dev-setup/windows/running-lk-7.png){ width="600" }
213+
</figure>
214+
215+
6. The file should open by default (if not, double click it to open it). You will see a screen like this:
216+
217+
<figure markdown="span">
218+
![alt text](../../images/dev-setup/windows/running-lk-8.png){ width="600" }
219+
</figure>
220+
221+
8. **We're going to paste a lot of text here!** Here is the contents to paste into this file:
222+
223+
```
224+
APP_NAME=Lorekeeper
225+
APP_ENV=local
226+
APP_KEY=
227+
APP_DEBUG=true
228+
APP_URL=http://localhost
229+
230+
CONTACT_ADDRESS=
231+
DEVIANTART_ACCOUNT=
232+
233+
LOG_CHANNEL=stack
234+
DB_CONNECTION=mysql
235+
DB_HOST=127.0.0.1
236+
DB_PORT=3306
237+
DB_DATABASE=lorekeeper
238+
DB_USERNAME=root
239+
DB_PASSWORD=
240+
241+
BROADCAST_DRIVER=log
242+
CACHE_DRIVER=file
243+
QUEUE_CONNECTION=sync
244+
SESSION_DRIVER=file
245+
SESSION_LIFETIME=120
246+
247+
BROADCAST_DRIVER=log
248+
CACHE_DRIVER=file
249+
QUEUE_CONNECTION=sync
250+
SESSION_DRIVER=file
251+
SESSION_LIFETIME=120
252+
253+
REDIS_HOST=127.0.0.1
254+
REDIS_PASSWORD=null
255+
REDIS_PORT=6379
256+
257+
MAIL_DRIVER=smtp
258+
MAIL_HOST=smtp.mailtrap.io
259+
MAIL_PORT=2525
260+
MAIL_USERNAME=null
261+
MAIL_PASSWORD=null
262+
MAIL_ENCRYPTION=null
263+
264+
AWS_ACCESS_KEY_ID=
265+
AWS_SECRET_ACCESS_KEY=
266+
AWS_DEFAULT_REGION=us-east-1
267+
AWS_BUCKET=
268+
269+
PUSHER_APP_ID=
270+
PUSHER_APP_KEY=
271+
PUSHER_APP_SECRET=
272+
PUSHER_APP_CLUSTER=mt1
273+
274+
MIX_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
275+
MIX_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"
276+
```
277+
278+
9. Save the file. Now, go back to the terminal. We are going to run a few setup commands. Type in `php artisan key:generate`. You will see something like this:
279+
280+
<figure markdown="span">
281+
![alt text](../../images/dev-setup/windows/running-lk-9.png){ width="600" }
282+
</figure>
283+
284+
10. Next, type in `php artisan migrate`. This will populate the database with all of the tables that Lorekeeper needs to function. You'll see a LOT of text start to fly by. It should look like this when completed:
285+
286+
<figure markdown="span">
287+
![alt text](../../images/dev-setup/windows/running-lk-10.png){ width="600" }
288+
</figure>
289+
290+
!!! info "Adding MySQL to your PATH Variable"
291+
292+
If you run into an error when running `php artisan migrate`, you may need to add MySQL to your computer's PATH variable.
293+
294+
1. Open your start menu and search for "edit system environment variables".
295+
<figure markdown="span">
296+
![start menu with edit environment variables selected](../../images/dev-setup/windows/env-variables-1.png){ width="300" }
297+
</figure>
298+
299+
2. Click "Environment Variables" in the pop-up.
300+
301+
<figure markdown="span">
302+
![start menu with edit environment variables selected](../../images/dev-setup/windows/env-variables-2.png){ width="300" }
303+
</figure>
304+
305+
3. Under "System Variables", selected "Path" and then "Edit..."
306+
307+
<figure markdown="span">
308+
![selecting path and then clicking edit on system variables](../../images/dev-setup/windows/env-variables-3.png){ width="300" }
309+
</figure>
310+
311+
4. Click "New".
312+
313+
<figure markdown="span">
314+
![selecting new on environment variables window](../../images/dev-setup/windows/env-variables-4.png){ width="300" }
315+
</figure>
316+
317+
5. Type in the location of your MySQL bin folder. For example, if you followed our XAMPP guide, this will be located `C:\xampp\mysql\bin`. Click OK to save.
318+
319+
<figure markdown="span">
320+
![entering mysql path into environment variables window](../../images/dev-setup/windows/env-variables-5.png){ width="300" }
321+
</figure>
322+
323+
6. Restart Visual Studio Code as well as any other command prompts you have open for the changes to reflect.
324+
325+
11. Now for some Lorekeeper-specific commands. Run `php artisan add-site-settings` to populate the database with the site settings. It should look like this when completed:
326+
327+
<figure markdown="span">
328+
![alt text](../../images/dev-setup/windows/running-lk-12.png){ width="600" }
329+
</figure>
330+
331+
12. Then run `php artisan add-text-pages`. This will add the default text pages for LK:
332+
333+
<figure markdown="span">
334+
![alt text](../../images/dev-setup/windows/running-lk-11.png){ width="600" }
335+
</figure>
336+
337+
13. Next run `php artisan copy-default-images`. This will add the default images for various features on LK:
338+
339+
<figure markdown="span">
340+
![alt text](../../images/dev-setup/windows/running-lk-16.png){ width="600" }
341+
</figure>
342+
343+
14. Finally, we will run the command `php artisan setup-admin-user`. This will create user #1, the default admin account. The email and details you give it do not need to be real, but make them something you'll remember easily.
344+
345+
- `Proceed to create account with this information? (yes/no)` Answer **yes**.
346+
- `Are you on a local/testing instance and not a live site? (yes/no)` Answer **yes**.
347+
- `Would you like to mark your email address as verified and enter an alias now? (yes/no)` Answer **yes**.
348+
349+
The important details to mark as `yes` have been highlighted in red.
350+
351+
<figure markdown="span">
352+
![alt text](../../images/dev-setup/windows/running-lk-13.png){ width="600" }
353+
</figure>
354+
355+
15. Now, go to `http://localhost` in your browser. You can also access this by pressing the "Admin" button next to "Apache" in XAMPP.
356+
357+
<figure markdown="span">
358+
![alt text](../../images/dev-setup/windows/running-lk-15.png){ width="600" }
359+
</figure>
360+
361+
## Setup Complete
362+
363+
You have finished installing a local copy of Lorekeeper. You can login as the admin account you just set up, and begin trying out the different features.
364+
365+
<figure markdown="span">
366+
![alt text](../../images/dev-setup/windows/running-lk-14.png){ width="600" }
367+
</figure>
368+
369+
When you are ready, you can move onto [configuration or setting up a live website](../setup-index.md).

0 commit comments

Comments
 (0)