Skip to content

Commit 4bcb609

Browse files
darcywong00darcywong00
authored
Merge pull request #311 from keymanapp/chore/A19S14-merge-master-into-staging
auto: A19S14 merge master into staging
2 parents 4679fff + 7532ade commit 4bcb609

File tree

15 files changed

+427
-96
lines changed

15 files changed

+427
-96
lines changed

‎README.md‎

Lines changed: 74 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,116 +1,111 @@
11
# api.keyman.com
22

3-
The following is outdated and will be replaced with Docker/Apache
3+
This is the source for the website https://api.keyman.com/, which hosts the
4+
database backend for Keyman websites. This site runs on Apache in a Docker
5+
container, and the database itself runs on SQL Server for Linux in a separate
6+
container.
47

5-
## Configuration
8+
## Other Keyman websites
69

7-
Currently, this site runs only on a Windows host with IIS and Microsoft SQL Server.
10+
* **[api.keyman.com]** - database backend for Keyman websites
11+
* **[help.keyman.com]** - documentation home for Keyman
12+
* **[keyman.com]** - Keyman home
13+
* **[keymanweb.com]** - KeymanWeb online keyboard
14+
* **[s.keyman.com]** - static Javascript, font, and related resources
15+
* **[website-local-proxy]** - run all Keyman sites on localhost on the same port
816

9-
## Prerequisites
17+
## How to run api.keyman.com locally
1018

11-
* Windows
12-
* Chocolatey
13-
* PHP 7.4
14-
* MS SQL Server 2016 or later including FullText Search
19+
When run locally, this site can be accessed at http://localhost:8058 or
20+
http://api.keyman.com.localhost:8058.
1521

16-
* `configure.ps1` automatically installs chocolatey, PHP, Composer, SQL Server and PHP-PDO driver
17-
for SQL Server. This script is not particularly sophisticated, so for manual config, copy and
18-
paste elements from the script.
22+
**Recommended:** Use [website-local-proxy] to run multiple keyman.com sites
23+
all from the same port (default port 80).
1924

20-
## Setup
25+
**Recommended:** Use [shared-sites] to control startup and shutdown of all
26+
keyman.com sites together.
2127

22-
1. Install the dependencies:
28+
### Prerequisites
2329

24-
```
25-
composer install
26-
```
27-
28-
2. Configure your local environment by copying tools/db/localenv.php.in to tools/db/localenv.php
29-
and completing the details therein.
30-
31-
3. Build the backend database from live data:
30+
The host machine needs the following apps installed:
31+
* [Git]
32+
* Bash 5.x (on Windows, you can use Git Bash that comes with [Git])
33+
* [Docker Desktop]
3234

33-
```
34-
composer build
35-
```
35+
<details>
36+
<summary>Configuration of Docker on Windows</summary>
3637

37-
## Tests
38+
On Windows machines, you can setup Docker in two different ways, either of
39+
which should work:
40+
* [Enable Hyper-V on Windows 11](https://techcommunity.microsoft.com/t5/educator-developer-blog/step-by-step-enabling-hyper-v-for-use-on-windows-11/ba-p/3745905)
41+
* [WSL2](https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-10#1-overview)
3842

39-
Test suites run with mock data from the tests/data folder. If this data is refreshed, fixtures
40-
will probably need to be updated accordingly as the data in them will have become stale.
43+
</details>
4144

42-
To run tests:
45+
### Actions
4346

44-
```
45-
composer test
46-
```
47+
#### Build the Docker image
4748

48-
To force a rebuild of the test database (e.g. if schema changes):
49+
The first time you want to start up the site, or if there have been Docker
50+
configuration changes, you will need to rebuild the Docker images. Start a bash
51+
shell, and from this folder, run:
4952

50-
```
51-
TEST_REBUILD=1 composer test
53+
```sh
54+
./build.sh build
5255
```
5356

54-
## Configuring a new Azure Database
57+
#### Start the Docker container
5558

56-
1. Create an Azure SQL Server
57-
2. Create an Azure SQL Database, e.g. called 'keymanapi'
58-
3. Run the following script on the master database, replacing password as necessary:
59+
To start up the website, in bash, run:
5960

61+
```sh
62+
./build.sh start --debug
6063
```
61-
-- logins for staging
62-
CREATE LOGIN [k0] WITH PASSWORD=N'password'
63-
GO
64-
65-
CREATE LOGIN [k1] WITH PASSWORD=N'password'
66-
GO
6764

68-
-- logins for production
69-
CREATE LOGIN [production_k0] WITH PASSWORD=N'password'
70-
GO
65+
Once the container starts, you can access the api.keyman.com site at
66+
http://localhost:8058 or http://api.keyman.com.localhost:8058
7167

72-
CREATE LOGIN [production_k1] WITH PASSWORD=N'password'
73-
GO
74-
```
68+
#### Stop the Docker container
7569

76-
4. Run the following script on the keymanapi database:
70+
In bash, run:
7771

72+
```sh
73+
./build.sh stop
7874
```
79-
-- Schemas, users and roles for staging
80-
CREATE SCHEMA [k0]
81-
GO
82-
83-
CREATE SCHEMA [k1]
84-
GO
8575

86-
CREATE USER [k0] FOR LOGIN [k0] WITH DEFAULT_SCHEMA=[k0]
87-
GO
76+
#### Remove the Docker container and image
8877

89-
CREATE USER [k1] FOR LOGIN [k1] WITH DEFAULT_SCHEMA=[k1]
90-
GO
78+
In bash, run:
9179

92-
ALTER ROLE db_owner ADD MEMBER k0
93-
GO
80+
```sh
81+
./build.sh clean
82+
```
9483

95-
ALTER ROLE db_owner ADD MEMBER k1
96-
GO
84+
#### Running tests
9785

98-
-- Schemas, users and roles for production
99-
CREATE SCHEMA [production_k0]
100-
GO
86+
Test suites run with mock data from the tests/data folder. To check APIs, broken
87+
links and .php file conformance, when the site is running, in bash, run:
10188

102-
CREATE SCHEMA [production_k1]
103-
GO
89+
```sh
90+
./build.sh test
91+
```
10492

105-
CREATE USER [production_k0] FOR LOGIN [production_k0] WITH DEFAULT_SCHEMA=[production_k0]
106-
GO
93+
To force a rebuild of the test database from the mock data (for example if
94+
schema changes and this is not automatically detected):
10795

108-
CREATE USER [production_k1] FOR LOGIN [production_k1] WITH DEFAULT_SCHEMA=[production_k1]
109-
GO
96+
```sh
97+
./build.sh test --rebuild-test-fixtures
98+
```
11099

111-
ALTER ROLE db_owner ADD MEMBER production_k0
112-
GO
100+
[Git]: https://git-scm.com/downloads
101+
[Docker Desktop]: https://docs.docker.com/get-docker/
102+
[api.keyman.com]: https://github.com/keymanapp/api.keyman.com
103+
[help.keyman.com]: https://github.com/keymanapp/help.keyman.com
104+
[keyman.com]: https://github.com/keymanapp/keyman.com
105+
[keymanweb.com]: https://github.com/keymanapp/keymanweb.com
106+
[s.keyman.com]: https://github.com/keymanapp/s.keyman.com
107+
[website-local-proxy]: https://github.com/keymanapp/website-local-proxy
108+
[shared-sites]: https://github.com/keymanapp/shared-sites
109+
[enable Hyper-V]: https://techcommunity.microsoft.com/t5/educator-developer-blog/step-by-step-enabling-hyper-v-for-use-on-windows-11/ba-p/3745905
110+
[enable WSL2]: https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-10#1-overview
113111

114-
ALTER ROLE db_owner ADD MEMBER production_k1
115-
GO
116-
```

‎build.sh‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
## START STANDARD SITE BUILD SCRIPT INCLUDE
33
readonly THIS_SCRIPT="$(readlink -f "${BASH_SOURCE[0]}")"
44
readonly BOOTSTRAP="$(dirname "$THIS_SCRIPT")/resources/bootstrap.inc.sh"
5-
readonly BOOTSTRAP_VERSION=v1.0.6
5+
readonly BOOTSTRAP_VERSION=v1.0.7
66
[ -f "$BOOTSTRAP" ] && source "$BOOTSTRAP" || source <(curl -fs https://raw.githubusercontent.com/keymanapp/shared-sites/$BOOTSTRAP_VERSION/bootstrap.inc.sh)
77
## END STANDARD SITE BUILD SCRIPT INCLUDE
88

@@ -28,6 +28,7 @@ builder_describe \
2828
"start" \
2929
"stop" \
3030
"test" \
31+
"--rebuild-test-fixtures Rebuild the test fixtures from live data" \
3132
":db Build the database" \
3233
":app Build the site"
3334

@@ -37,6 +38,10 @@ function test_docker_container() {
3738
echo "TIER_TEST" > tier.txt
3839
# Note: ci.yml replicates these
3940

41+
if builder_has_option --rebuild-test-fixtures; then
42+
touch rebuild-test-fixtures.txt
43+
fi
44+
4045
# Run unit tests
4146
docker exec $API_KEYMAN_CONTAINER_DESC sh -c "vendor/bin/phpunit --testdox"
4247

@@ -92,13 +97,17 @@ function start_docker_container_db() {
9297

9398
# Setup database
9499
builder_echo "Setting up DB container"
95-
docker run -m 2048m --rm -d -p $PORT:1433 \
100+
docker run --rm -d -p $PORT:1433 \
96101
-e "ACCEPT_EULA=Y" \
97102
-e "MSSQL_AGENT_ENABLED=true" \
98103
-e "MSSQL_SA_PASSWORD=yourStrong(\!)Password" \
99104
--name $CONTAINER_DESC \
100105
$CONTAINER_NAME
101106

107+
builder_echo "Sleeping for 30 seconds to give database time to spin up"
108+
builder_echo "(DB may crash if connected to, too early, on some systems)"
109+
sleep 30s
110+
102111
builder_echo green "SQL Server Listening on localhost:$PORT"
103112
}
104113

@@ -137,6 +146,8 @@ function start_docker_container_app() {
137146
ADD_HOST="--add-host host.docker.internal:host-gateway"
138147
fi
139148

149+
builder_echo "Checking network settings"
150+
140151
db_ip=$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' ${API_KEYMAN_DB_IMAGE_NAME})
141152

142153
builder_echo "Spooling up site container"

‎resources/init-container.sh‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,16 @@
11
#!/usr/bin/env bash
22

3-
echo "---- Sleep 15 Before Generating DB ----"
3+
openssl version
4+
uname -a
5+
6+
echo "---- Sleep 15 for SQL Server to start before generating DB ----"
47
sleep 15;
58

69
# If we know we are immediately going to run tests, there's no need to build
710
# the database and then rebuild it again as a test database!
811
if [[ ! -f /var/www/html/tier.txt ]] || [[ $(</var/www/html/tier.txt) != TIER_TEST ]]; then
912
php /var/www/html/tools/db/build/build_cli.php -f
13+
else
14+
echo "tier.txt contains TIER_TEST -- not generating database!"
15+
echo "(For normal use, delete tier.txt and restart)"
1016
fi

‎schemas/.htaccess‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,35 @@
22
# versioned schema files rather than to the base, so we will not add extra
33
# redirects here for new schemas
44

5+
6+
# keyboard_info.schema.json (deprecates keyboard_info.source.json, keyboard_info.distribution.json)
7+
RewriteRule "^keyboard_info\.schema\.json$" "/schemas/keyboard_info/2.0/keyboard_info.schema.json" [END]
8+
59
# keyboard_info.distribution.json (deprecated by keyboard_info.schema.json)
610
RewriteRule "^keyboard_info\.distribution\.json$" "/schemas/keyboard_info.distribution/1.0.6/keyboard_info.distribution.json" [END]
711

812
# keyboard_info.source.json (deprecated by keyboard_info.schema.json)
913
RewriteRule "^keyboard_info\.source\.json$" "/schemas/keyboard_info.source/1.0.6/keyboard_info.source.json" [END]
1014

15+
1116
# keyboard_json.json
1217
RewriteRule "^keyboard_json\.json$" "/schemas/keyboard_json/1.0/keyboard_json.json" [END]
1318

14-
# model_info.distribution.json"
19+
20+
# model_info.schema.json (deprecates model_info.source.json, model_info.distribution.json)
21+
RewriteRule "^model_info\.schema\.json$" "/schemas/model_info/2.0/model_info.schema.json" [END]
22+
23+
# model_info.distribution.json" (deprecated by model_info.schema.json)
1524
RewriteRule "^model_info\.distribution\.json$" "/schemas/model_info.distribution/1.0.1/model_info.distribution.json" [END]
1625

17-
# model_info.source.json
26+
# model_info.source.json (deprecated by model_info.schema.json)
1827
RewriteRule "^model_info\.source\.json$" "/schemas/model_info.source/1.0.1/model_info.source.json" [END]
1928

29+
2030
# model-search.json
2131
RewriteRule "^model-search\.json$" "/schemas/model-search/1.0.1/model-search.json" [END]
2232

33+
2334
# package.json (renamed to kmp.schema.json)
2435

2536
# note: package.json has been renamed to kmp.schema.json to reduce confusion with
@@ -31,14 +42,18 @@ RewriteRule "^package/1\.0\.1/package\.json$" "/schemas/kmp/1.0.1/kmp.schema.jso
3142
RewriteRule "^package/1\.0\.2/package\.json$" "/schemas/kmp/1.0.2/kmp.schema.json" [END]
3243
RewriteRule "^package/1\.1\.0/package\.json$" "/schemas/kmp/1.1.0/kmp.schema.json" [END]
3344

45+
3446
# package-version.json
3547
RewriteRule "^package-version\.json$" "/schemas/package-version/1.0.1/package-version.json" [END]
3648

49+
3750
# search.json
3851
RewriteRule "^search\.json$" "/schemas/search/3.0/search.json" [END]
3952

53+
4054
# version.json
4155
RewriteRule "^version\.json$" "/schemas/version/2.0/version.json" [END]
4256

57+
4358
# windows-update.json
4459
RewriteRule "^windows-update\.json$" "/schemas/windows-update/17.0/windows-update.json" [END]

‎schemas/model_info.distribution/README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
# model_info
22

3+
Deprecated: see [model_info/README.md](../model_info/README.md)
4+
35
* model_info.source.json
46
* model_info.distribution.json
57

68
Documentation at https://help.keyman.com/developer/cloud/model_info
79

8-
## 2019-01-31 1.0 beta
9-
* Initial version, seeded from .keyboard_info specification
10-
1110
## 2020-09-21 1.0.1
1211
* Relaxed the URL definitions in the schema so extension is no longer tested
12+
13+
## 2019-01-31 1.0 beta
14+
* Initial version, seeded from .keyboard_info specification

‎schemas/model_info.source/README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
# model_info
22

3+
Deprecated: see [model_info/README.md](../model_info/README.md)
4+
35
* model_info.source.json
46
* model_info.distribution.json
57

68
Documentation at https://help.keyman.com/developer/cloud/model_info
79

8-
## 2019-01-31 1.0 beta
9-
* Initial version, seeded from .keyboard_info specification
10-
1110
## 2020-09-21 1.0.1
1211
* Relaxed the URL definitions in the schema so extension is no longer tested
12+
13+
## 2019-01-31 1.0 beta
14+
* Initial version, seeded from .keyboard_info specification

0 commit comments

Comments
 (0)