From 36a67b77f6275bb8f52c587717ca6f41814266ea Mon Sep 17 00:00:00 2001 From: Ryan McCullagh Date: Sun, 10 Nov 2024 06:15:28 -0600 Subject: [PATCH 1/3] fix many typos --- api/deployments/cancel-deployment.md | 13 ++++---- api/deployments/get.md | 13 ++++---- api/deployments/post.md | 30 ++++++++++------- configuration/storage.md | 21 +++++++----- databases/ssh.md | 10 ++---- deployments/hooks/index.md | 49 +++++++++++++++++----------- deployments/index.md | 33 ++++++++++--------- environments/password-protection.md | 7 ++-- index.md | 9 +++-- instances/index.md | 2 +- 10 files changed, 107 insertions(+), 80 deletions(-) diff --git a/api/deployments/cancel-deployment.md b/api/deployments/cancel-deployment.md index ba2088e..b9ad82f 100644 --- a/api/deployments/cancel-deployment.md +++ b/api/deployments/cancel-deployment.md @@ -1,22 +1,23 @@ # Cancel Deployment -```bash +```http POST /v1/instances/{instance_id}/deployments/{deployment_id}/cancel ``` ## Parameters -Parameter | Type | In | Description -------------- | ------|------ |------------------ -instance_id | string | uri | The instance id of the environment + +Parameter | Type | In | Description +------------- | -------|------ |------------------ +instance_id | string | uri | The instance id of the environment deployment_id | string | uri | The deployment ID ## Response `200 OK` -```bash +```json { "id": 838, "status": "cancelling" } -``` \ No newline at end of file +``` diff --git a/api/deployments/get.md b/api/deployments/get.md index da9f022..ec57d12 100644 --- a/api/deployments/get.md +++ b/api/deployments/get.md @@ -1,22 +1,23 @@ # Get a deployment -```bash +```http GET /v1/instances/{instance_id}/deployments/{deployment_id} ``` ## Parameters -Parameter | Type | In | Description -------------- | ------|------ |------------------ -instance_id | string | uri | The instance id of the environment + +Parameter | Type | In | Description +------------- | -------|------ |------------------ +instance_id | string | uri | The instance id of the environment deployment_id | string | uri | The deployment ID ## Response `200 OK` -```bash +```json { "id": 838, "status": "cancelled" } -``` \ No newline at end of file +``` diff --git a/api/deployments/post.md b/api/deployments/post.md index 0aaeb1a..23d6361 100644 --- a/api/deployments/post.md +++ b/api/deployments/post.md @@ -1,25 +1,32 @@ # Create a deployment -You may invoke a deployment on your instance with an optional archive file. This archive file allows you to -upload a complete version of your application without having to use Git. A common use case for deploying with an archive file is when you're using a pipeline provider such as GitHub actions. +You may invoke a deployment on your instance with an optional archive file. +This archive file allows you to upload a complete version of your +application without having to use Git. -See the [Amezmo GitHub Actions](https://github.com/amezmo/github-actions-demo) repository for a complete working example of using GitHub actions to deploy an application. +A common use case for deploying with an archive file is when +you're using a pipeline provider such as GitHub actions. + +See the [Amezmo GitHub Actions](https://github.com/amezmo/github-actions-demo) demo +repository for a guide to Deploying PHP applications +with [GitHub actions](https://www.amezmo.com/laravel-hosting-guides/deploying-laravel-with-github-actions). Deployments with an [archive file](/docs/how-to-guides/creating-zip-files-for-api-deployments) work exactly like regular Git deployments. -When deploying with the Amezmo API, The `after.pull` +When deploying with the Amezmo API, The `after.pull` [deployment hook](/docs/deployments/hooks) will not be run. -Instead, use the [after.extract](/docs/deployments/hooks/after-extract) hook to run code after extracting your archive. +Instead, use the [after.extract](/docs/deployments/hooks/after-extract) +hook to run code after extracting your archive. -```bash +```http POST /v1/instances/{instance_id}/deployments ``` ## Parameters -Parameter | Type | In | Description -------------- | ------------- +Parameter | Type | In | Description +------------- | ------|------ |------------------ api_key | string | header | **Required**. Your [API key](/docs/api/authentication). environment | string | body | **Required**. The [environment](/docs/api/environments) name for this deployment. This can be `production` or `staging`. instance_id | string | uri | **Required**. The ID of the instance that this deployment will be executed on. @@ -31,10 +38,9 @@ pusher | string | body | The email address of the user that invoked the commit | string | body | The git commit hash tag | string | body | The git tag - ## Code samples -```bash +```curl curl --request POST \ --url https://api.amezmo.com/v1/instances/{instance_id}/deployments \ --header 'Authorization: Bearer {api_key}' \ @@ -52,7 +58,7 @@ curl --request POST \ `201` Created -```bash +```json { "id": 838, "status": "pending" @@ -60,5 +66,5 @@ curl --request POST \ ``` ## Resources -- [How to create a ZIP archive for API deployments](/docs/how-to-guides/creating-zip-files-for-api-deployments) +- [How to create a ZIP archive for API deployments](/docs/how-to-guides/creating-zip-files-for-api-deployments) diff --git a/configuration/storage.md b/configuration/storage.md index f86fc5d..5f60fcf 100644 --- a/configuration/storage.md +++ b/configuration/storage.md @@ -2,12 +2,18 @@ The `/webroot/storage` directory is available for your **production** persistent storage needs. By default, this directory is created for you when you launch an instance. You should configure your application to -write files to this directory if you need to persist user uploaded content, or other files across deployments. For staging environements, the persistent storage directory follows the same pattern but it's located under `/webroot/$stagingRootDirectory/storage`. To find the value of `$stagingRootDirectory`, search for "Storage directory" under the Git tab. +write files to this directory if you need to persist user uploaded content, or other files across deployments. + +For your staging environments, the persistent storage directory follows the same pattern +and it's located under `/webroot/$stagingRootDirectory/storage`. +To find the value of `$stagingRootDirectory`, search for "Storage directory" +under your Git tab in the Amezmo Dashboard To automatically link a deployment your persistent storage directory, see [Setting up the storage directory](/docs/how-to-guides/setting-up-the-storage-directory). ## Directory layout + ```bash /webroot |----logs @@ -28,21 +34,20 @@ any files created from your hooks will have correct and expected permissions. Am The `/webroot/storage/public` is created for [public file uploads](/docs/configuration/public-directory). Files uploaded to this directory can be accessible from your domain by creating a symbolic link -from `/webroot/storage/public` to `/webroot/current/public`. See the [public directory documentation](/docs/configuration/public-directory) for more details. +from `/webroot/storage/public` to `/webroot/current/public`. +See the [public directory documentation](/docs/configuration/public-directory) for more details. When uploading files from your PHP app, the default owner and group is `www-data`. At this time, Amezmo has chosen not to modify the default PHP FPM configuration in an effort to run the FPM daemon as a non-shell capable access user. We recommend the following file system permissions when writing and uploading new files to your instance. - ## Recommend file permissions settings The following permission configuration is Amezmo's recommendation for PHP applications hosted on Amezmo. Note that the example shows a Laravel based configuration array, but these permissions are not specific to Laravel. Any PHP application hosted on Amezmo should use these permissions and settings. - This file is located at `app/config/filesystems.php`. The ```php @@ -85,13 +90,13 @@ return [ ]; ``` -The above permissions provide expected behavior across all application areas. With the above file permissions, -your depoyment hooks may read and write existing and new files and your workers may read and write existing -and new files. +The above permissions provide expected behavior across all application areas. +With the above file permissions, your deployment hooks may read and write existing and +new files and your workers may read and write existing and new files. ## Resources + - [How to Persist Storage Across PHP Deployments on Amezmo Part 1](https://www.youtube.com/watch?v=A-iBIfch6Bw) Video - [How to Change the Default Storage Path in Laravel](https://www.amezmo.com/blog/how-to-change-the-default-storage-path-in-laravel/) - [Laravel deployment hook for persistent storage](https://github.com/amezmo/demo.amezmo.com/blob/master/.amezmo/before.deploy) - [Craft CMS deployment hook for persistent storage](https://github.com/amezmo/craftcms-demo/blob/master/.amezmo/before.deploy) - diff --git a/databases/ssh.md b/databases/ssh.md index 96fc67e..37bdb3b 100644 --- a/databases/ssh.md +++ b/databases/ssh.md @@ -5,10 +5,9 @@ then MySQL will available directly, and with any instance on the shared network. Amezmo dashboard, you can backup, restore, and check the status of your database. After ensuring that -[SSH is enabled](/docs/instances/ssh#enable-ssh) on your instance, +[SSH is enabled](/docs/instances/enable-or-disable-ssh) on your instance, then go to Overview > Server Details and find your **SSH port**. An example SSH command is provided for you below: - ```bash ssh -i -p \ -L 127.0.0.1:3306:127.0.0.1:3306 \ @@ -18,14 +17,11 @@ ssh -i -p \ **Important**: When you connect to your instance with the SSH command, you'll be able to access your database over a secure SSH tunnel. - In this example command, the local IP address is `127.0.0.1`, and the local port -is `3306`. -If you're already running a MySQL server on your local machine, be sure to change the port in the command to something else, such as 3307. +is `3306`. If you're already running a MySQL server on your local machine, +be sure to change the port in the command to something else, such as 3307. ## Requirements Before you can access your MySQL database via SSH, you must upload your public SSH key to your instance. [Learn more](/docs/instances/ssh) about accessing your instances resources through SSH. - - diff --git a/deployments/hooks/index.md b/deployments/hooks/index.md index f45e121..b0b7419 100644 --- a/deployments/hooks/index.md +++ b/deployments/hooks/index.md @@ -7,12 +7,11 @@ A set of environment variables are given to the script, for your reference. For example, the file [after.pull](/docs/deployments/hooks/after-pull) is executed for the event After Pull. - ## Hook files + Hooks are files. In the below sample application directory structure, the `.amezmo` directory is where you define your "hook" scripts. - ```bash # A sample laravel application root directory. # The `tree -a -L 2 .` command was run inside a Laravel app's root directory. @@ -44,11 +43,20 @@ As part of the deployment process, Amezmo will run a chmod across your target de any files created from your hooks will have correct and expected permissions. Amezmo ensures the owner/group is `www-data:deployer`. This allows for expected permissions across all areas of your application. +For directories, these are the permissions. + +```sh +2775/drwxrwxr-x +``` -For directories, the permissions are `2775/drwxrwxr-x`, for files the permissions are `0664/-rw-rw--r--`. +For files, these are the permissions. +```sh +0664/-rw-rw--r-- +``` ## Hook list + - [before.pull](/docs/deployments/hooks/before-pull) - [after.pull](/docs/deployments/hooks/after-pull) - [after.extract](/docs/deployments/hooks/after-extract) @@ -57,41 +65,44 @@ For directories, the permissions are `2775/drwxrwxr-x`, for files the permission - [deploy.success](/docs/deployments/hooks/deploy-success) - [deploy.failure](/docs/deployments/hooks/deploy-failure) -## .env -The [most recent .env file](/docs/configuration/dotenv), which is the one that you see in the dashboard within the Configuration tab, -is placed into the newly created [deployment directory](/docs/deployments/directories) immediately completion of git pull. -This allows your hooks to use the contents of the `.env` if you desire. -However, the `.env` file loading does not happen automatically. +## Environment File + +Your [most recent .env file](/docs/configuration/dotenv), which is the one that you see in your +Amezmo Dashboard under the Configuration tab, is placed into the +newly created [deployment directory](/docs/deployments/directories) +immediately completion of git pull. + +This allows your hooks to use the contents of +the `.env` if you desire. However, the `.env` file loading does not happen automatically. To accomplish this, simply edit your hook file to load it before doing anything else. ## Secrets + [Encrypted environment variables](/docs/secrets) are injected into the hooks environment and exist in memory only. You may access them inside your hook file using the bash syntax for variables such as `$MY_SECRET_VARIABLE_NAME`. Secrets will never be written to disk and only decrypted to execute hooks. - - ## Environment variables -Your hook script has access to the following pre-defined environment variables. -In addition to these enviroment variables, Amezmo injects your secret variables as well. For more -information about secrets, see the [Secrets Overview](/docs/secrets) page. +Your hook script has access to the following pre-defined environment variables. +In addition to these environment variables, Amezmo injects your secret variables as well. For more +information about secrets, see the [Secrets Overview](/docs/secrets) page. -| Variable | Description +Variable | Description -----------|------------ APPLICATION_ROOT | This is where your code is located on the server in the form of `deployment_${sequence_number}.${short_commit_id}` -COMMIT_ID | Git commit hash of the currently executing deployment +COMMIT_ID | Git commit hash of the currently executing deployment NODE_PATH | The path to the global node.js package binaries COMPOSER_MEMORY_LIMIT | set to `-1` -PERSISTENT_STORAGE_DIRECTORY | Path to the [persistent storage](/docs/configuration/storage) directory -APP_DOMAIN | Internal domain name for the environmnt +PERSISTENT_STORAGE_DIRECTORY | Path to the [persistent storage](/docs/configuration/storage) directory +APP_DOMAIN | Internal domain name for the environment REPO_NAME | The name of the repository currently being deployed DEPLOY_BRANCH | The name of the branch currently being deployed TARGET_HOOK | The name of hook being executed. This is one of the values listed in the [Hook list](/docs/deployments/hooks/#hook-list) RELEASE_NUMBER | The generated release number. The value is in the form of `deployment_${sequence_number}.${short_commit_id}` -DEPLOYMENT_DIRECTORY | The fully qualified path to the current in progress deployment. +DEPLOYMENT_DIRECTORY | The fully qualified path to the current in progress deployment. APP_TYPE | The application type ID such as `drupal`, `laravel`, or `crafctms` ENVIRONMENT_NAME | The name of the [application environment](/docs/environments) @@ -101,6 +112,6 @@ On the Deployments tab, you can see a list of your deployments. To view a single deployment click on the link in the status column. Note that, Amezmo will only show the hooks that were executed in the table below. - ## Limits + - There is a 10 minute limit on hook execution diff --git a/deployments/index.md b/deployments/index.md index 8c03ee4..117eb6f 100644 --- a/deployments/index.md +++ b/deployments/index.md @@ -1,27 +1,26 @@ # Deployments -Amezmo implements atomic, real-time deployments based on your `git push` -activity. When your repo has new push events, Amezmo will be notified and +Amezmo implements atomic, real-time deployments based on your `git push` +activity. When your repo has new push events, Amezmo will be notified and immediately begin a deployment process. You can use Amezmo to ensure your PHP application is highly available. Deployments -on Amezmo combine a series of atomic steps that operate in a pipeline. Pipeline -steps have success conditions. Conditions are checked as a prerequisite for -advancing to the next step in the pipeline. In the case of a negative +on Amezmo combine a series of atomic steps that operate in a pipeline. Pipeline +steps have success conditions. Conditions are checked as a prerequisite for +advancing to the next step in the pipeline. In the case of a negative success condition evaluation, your deployment pipeline safely terminates leaving -your active, or live site unaffected. +your active, or live site unaffected. -## Deployment pipeline success critera -You can keep your production site highly available to your users or -customers with Amezmo Atomic Deployments&mark. Amezmo deploys your -PHP application with a pipeline Atomicity. This gurantees invariability between -your live production site, and a failed deployment. There's no risk in -automating your [PHP deployments](/docs/git/). - -Amezmo deploys your PHP application to production in a pipeline comprised of -indivisible units of well-defined deployment tasks. +## Deployment pipeline success criteria +You can keep your production site highly available to your users or +customers with Amezmo Atomic Deployments™ Amezmo deploys your +PHP application with a pipeline Atomicity. Amezmo guarantees invariability between +your live production site, and a failed deployment. There's no risk in +automating your [PHP deployments](/docs/git/). +Amezmo deploys your PHP application to production in a pipeline comprised of +indivisible units of well-defined deployment tasks. ## Configuration files @@ -30,16 +29,20 @@ An `.env`, will be placed into your root any existing `.env` file your archive may have. ## Deployment directories + The deployment directory section describes the layout for zero-downtime deployments [Learn more](/docs/deployments/directories). ## Hooks + Amezmo's extensible deployment systems provides you the capability to run your own code at any step of the deployment process. [Learn more](/docs/deployments/hooks). ## Releases + After a successful deployment, then the deployment is considered a release. You may rollback to a previous release at anytime. [Learn more](/docs/deployments/releases). ## Fault tolerance + Your application will not be affected by a failed deployment, as Amezmo only releases your successful deployments. diff --git a/environments/password-protection.md b/environments/password-protection.md index 9743824..ff56db4 100644 --- a/environments/password-protection.md +++ b/environments/password-protection.md @@ -1,4 +1,4 @@ -# Password-protection +# Password protection By default, Amezmo doesn't configure your application to require a username/password to access it over HTTP. However, you may enforce such restriction. When enabled, this setting @@ -8,6 +8,5 @@ Implemented with Nginx's basic authentication module, you may define a username and password combination that must be provided before accessing your application. Passwords are hashed using the `crypt` algorithm and must be at least 8 characters. -While HTTP Authentication is enabled and username/password combination doesn't match what you've defined, -your application will respond with 401 (Authorization Required). - +Your application responds with [`401 Unauthorized`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401) +While HTTP Authentication is enabled and username and password combination doesn't match what you've defined. diff --git a/index.md b/index.md index 5495645..3eaa534 100644 --- a/index.md +++ b/index.md @@ -5,7 +5,8 @@ by the Amezmo community. With that being said, Amezmo welcomes all contributions on the public [Amezmo Docs](https://github.com/amezmo/docs) repo. ## How PHP Hosting Works On Amezmo -on Amezmo, your production sites will sustain uninterupted availibility + +on Amezmo, your production sites will sustain uninterrupted availability at all times. First, you must have be using `Git` with either Github, BitBucket, or GitLab. Secondly, your applications must be able to run outside your local machine. That is, your application should not be hardcoded to depend on @@ -21,24 +22,28 @@ and we'll customize your image to install any custom packages with [Apt](https://manpages.ubuntu.com/manpages/xenial/man8/apt-get.8.html). ## Amezmo PHP Hosting Components for Your Applications + Get details about setting up your PHP applications and server infrastructure on Amezmo. Learn about automated deployments, and more. For specific questions that are not answered here, we encourage you to join us on [Slack](/goslack). ### Instances + Launch a dedicated service instance, or a full stack instance. Scale up or down at anytime. [Learn more](/docs/instances). ### Databases + Run a fully managed dedicated instance of MySQL on Amezmo. Launch a database instance into your private network and let your other instances connect to it. [Learn more](/docs/databases). ### Deployments + Automatically deploy your PHP application with zero-downtime using Git. [Learn more](/docs/deployments). +## See Also -### See Also - [YouTube](https://www.youtube.com/@amezmo6464) - [GitHub](https://www.github.com/amezmo) - [PHP hosting Guides](https://www.amezmo.com/guides) diff --git a/instances/index.md b/instances/index.md index 23d2b8d..b7c861e 100644 --- a/instances/index.md +++ b/instances/index.md @@ -1,6 +1,6 @@ # Instances -Applications on Amezmo are backed by an optimzed Docker container instance. Each "instance" of an application +Applications on Amezmo are backed by an optimized Docker container instance. Each "instance" of an application is a isolated container running on reserved hardware resources. Amezmo was designed to run PHP apps. Launching an instance on Amezmo creates a single container instance with two environments From bc0baa67de091a4ede6e13fac3aa18003b323c73 Mon Sep 17 00:00:00 2001 From: Ryan McCullagh Date: Sun, 10 Nov 2024 06:22:00 -0600 Subject: [PATCH 2/3] add solr ref --- solr/configuration.md | 29 +++++++++++++++-------------- solr/index.md | 12 +++++++++++- 2 files changed, 26 insertions(+), 15 deletions(-) diff --git a/solr/configuration.md b/solr/configuration.md index 6132369..75f3fbc 100644 --- a/solr/configuration.md +++ b/solr/configuration.md @@ -1,21 +1,20 @@ # Solr configuration -Amezmo configures the Solr instance for Drupal with default credentials. The autogenerated -credentials may be found in your [dotenv](/docs/configuration/dotenv) file and within the -Configuration tab in your Amezmo dashboard. See below for the configuration that Amezmo +Amezmo configures the Solr instance for Drupal with default credentials. The autogenerated +credentials may be found in your [dotenv](/docs/configuration/dotenv) file and within the +Configuration tab in your Amezmo dashboard. See below for the configuration that Amezmo generates. -| Variable | Value | +Variable | Value --------------|------------------------------------------ -| `SOLR_HOST` | _See your Application details panel*_ -| `SOLR_CORE` | drupal | -| `SOLR_PORT` | 8983 +`SOLR_HOST` | See Overview > Application Details in your Amezmo Dashboard. +`SOLR_CORE` | drupal +`SOLR_PORT` | 8983 -\* To access your Application details panel go to Overview > Application details. +To access your Application details panel go to Overview > Application details. - -The `SOLR_HOST` value is what you will provide to your Drupal configuration form. -This is where your actual Solr server lives. This is unique to your instance and is only +The `SOLR_HOST` value is what you will provide to your Drupal configuration form. +This is where your actual Solr server lives. This is unique to your instance and is only available after you launch it. See below for an example host name. This screenshot highlights the Solr host which gets generated after your instance is launched. @@ -23,9 +22,11 @@ The Solr host value exist only after the instance is created. -To view your automatic dotenv variable set for Solr, see the screenshot below. This example shows -which variable set Amezmo generates. +To view your automatic dotenv variable set for Solr, see the screenshot below. This example shows +which variable set Amezmo generates. -Currently there is no mechanism to upload a Solr configset to Amezmo. Please reach out to [Support](/support) for assistance with this. +Currently there is no mechanism to upload a Solr +`configset` to Amezmo. +Please reach out to [Support](/support) for assistance with this. diff --git a/solr/index.md b/solr/index.md index 2ca576a..5d06977 100644 --- a/solr/index.md +++ b/solr/index.md @@ -3,6 +3,16 @@ The Solr full-text search platform is provided for Drupal applications. Amezmo provides this with the Advanced instance type. See below for some resources for getting started. +## Solr API + +From your [SSH](/docs/instances/ssh) session, you can check which cores are created with +this command + +```curl +curl http://localhost:${SOLR_PORT:-8983}/solr/admin/cores +``` + ## Resources -- [Solr configuration](/docs/solr/configuration) +- [Solr configuration](/docs/solr/configuration) +- [Solr Reference](https://solr.apache.org/guide/solr/latest/configuration-guide/config-api.html) \ No newline at end of file From 9fe5fe1b5b5b5ba9b210ded3b4e1d9a83e3ad3d9 Mon Sep 17 00:00:00 2001 From: Ryan McCullagh Date: Sun, 10 Nov 2024 07:14:04 -0600 Subject: [PATCH 3/3] add solr API examples --- solr/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/solr/index.md b/solr/index.md index 5d06977..61187a5 100644 --- a/solr/index.md +++ b/solr/index.md @@ -10,6 +10,8 @@ this command ```curl curl http://localhost:${SOLR_PORT:-8983}/solr/admin/cores +curl http://localhost:8983/solr/drupal/config +curl http://localhost:8983/solr/drupal/schema ``` ## Resources