# Aliyun OSS: Basic Implementation

> Canonical source: [Aliyun OSS: Basic Implementation](https://docs.hellowes.com/aliyun-oss-deployment/)

An Aliyun OSS destination uploads your published site file by file into an Alibaba Cloud Object Storage Service bucket. Create the bucket, give a RAM user permission to write to it, and enter its AccessKey in WCH.

## How WCH authenticates to Aliyun OSS

The Aliyun OSS destination uses an AccessKey pair: an AccessKey ID and an AccessKey Secret. The pair belongs to a RAM user, which is an Alibaba Cloud identity you create inside your account.

Create a RAM user for WCH alone and give it write access to one bucket. The AccessKey is a long-lived secret stored in WCH, so keep its permissions as narrow as possible. You can cut WCH's access at any time by disabling the AccessKey.

## What WCH sends

- **Individual files**, not a zip. Each page and asset becomes its own object in the bucket, at the same path it has on your site, for example `about/index.html`.
- **Files land at the top of the bucket.** If the project has a Root directory set in Settings, every file goes inside that folder instead. See [File Prefix and Root directory](/file-prefix-and-root-directory).
- **Content types are set.** WCH sets the Content-Type of each file from its extension, so HTML, CSS, JavaScript, images, and fonts are served correctly.
- **No ACL is set.** Each object uses the bucket's ACL.
- **Existing objects are overwritten.** An object with the same path is replaced by the new version.
- **No deletions.** Pages and assets you remove from your site stay in the bucket until you delete them.

WCH stores every page as a folder with an `index.html` inside, and the 404 page at `404/index.html`.

## 1. Create the bucket

1. In the Alibaba Cloud console, open Object Storage Service and click Create Bucket.
2. Enter a Bucket Name, for example `acme-website`.
3. Choose the Region closest to your visitors, for example China (Hangzhou).
4. Set the ACL to match how you will serve the site: Public Read if visitors reach the bucket directly, or Private if a CDN in front of it reads from the bucket.
5. Click OK.

Note the region. Its endpoint is what you enter in WCH, for example `oss-cn-hangzhou.aliyuncs.com`. The bucket's Overview page lists it.

## 2. Set up static website hosting

1. Open the bucket and go to Data Management, then Static Pages.
2. Set Default Homepage to `index.html`.
3. Turn on the subfolder homepage option, so a folder path such as `/about/` serves `about/index.html`.
4. Set Default 404 Page to `404/index.html`.
5. Save.

Serve the site through a custom domain mapped to the bucket, or through a CDN. Alibaba Cloud serves HTML files from the bucket's default domain as downloads, so visitors need your own domain to see the pages.

## 3. Create a RAM user for WCH

1. Open Resource Access Management (RAM), then Users, and click Create User.
2. Enter a Logon Name, for example `wch-oss-upload`.
3. Under Access Mode, select programmatic access (OpenAPI access), so the user gets an AccessKey.
4. Click OK.
5. Copy the AccessKey ID and AccessKey Secret.

> **Copy the AccessKey Secret immediately.** Alibaba Cloud shows it once. If you lose it, create a new AccessKey for the same user and update the destination in WCH.

## 4. Give the RAM user write access

WCH only needs to upload objects. Create a custom policy that allows exactly that on your bucket.

1. In RAM, go to Permissions, then Policies, and click Create Policy.
2. Choose the JSON editor and paste this policy, with your bucket name:

```
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["oss:PutObject"],
      "Resource": ["acs:oss:*:*:acme-website/*"]
    }
  ]
}
```

3. Name the policy, for example `wch-oss-upload`, and save it.
4. Go back to Users, open `wch-oss-upload`, and click Add Permissions.
5. Choose the policy you created and confirm.

## 5. Add the destination in WCH

1. Open your project, then Extensions, then Deployments.
2. Click + Add Deployment and choose Aliyun OSS as the Deployment Type.
3. Fill in the fields below and click Save.

Only team admins see Deployments.

### Fields

- **AccessKey ID**: from step 3.
- **AccessKey Secret**: from step 3.
- **Endpoint**: the endpoint of your bucket's region, for example `oss-cn-hangzhou.aliyuncs.com`.
- **Region (Optional)**: the region ID, for example `oss-cn-hangzhou`. The Endpoint already names the region, so you can leave this empty.
- **Bucket Name**: from step 1, for example `acme-website`.
- **File Name** and **Use project name**: leave the default. Aliyun OSS receives individual files, not a zip, so the file name does not change what lands in the bucket.
- **Is Production?**: turn on for your production bucket. A project can have one production Aliyun OSS destination. If another one already has it, WCH shows "You already have a production Aliyun OSS".

If you are sharing these values with someone else who will enter them, send them over a secure channel, never in plain-text email.

To change a value later, open Extensions, then Deployments, and click Update Configuration on the bucket's row.

## 6. Publish to the bucket

1. Publish your site to staging with Publish all pages and review the staging build.
2. On the Dashboard, find Aliyun OSS in the Deployment column. Each destination shows its bucket name.
3. Click Publish on the destination. A production destination's button says Promote.

Publishing webhooks cannot target an Aliyun OSS destination. Publish to Aliyun OSS from the Dashboard. See [Webhooks](/webhooks).

## Testing your changes

1. Publish to staging and check the pages you care about.
2. Publish to your Aliyun OSS destination.
3. Open Project Logs with View logs and look for "Deployed to Aliyun OSS successfully."
4. In the OSS console, open the bucket and confirm `index.html` and your page folders are there.
5. Open your site on its custom domain and check a few pages, including one that does not exist, to confirm the 404 page is served.

## Troubleshooting

- **Please enter Aliyun OSS Endpoint** or a similar message on Save: a required field is empty. AccessKey ID, AccessKey Secret, Endpoint, and Bucket Name are all required.
- **Deploying to Aliyun OSS Failed with error** followed by an access denied message: the RAM user has no `oss:PutObject` permission on this bucket, or the AccessKey is disabled. Check the policy in step 4 and the AccessKey's status.
- **Deploying to Aliyun OSS Failed with error** followed by a bucket or endpoint message: the Endpoint does not match the bucket's region, or the Bucket Name is misspelled.
- **Pages download instead of opening**: you are opening the bucket's default domain. Use your custom domain or CDN.
- **A folder URL shows an error but the full `index.html` URL works**: the subfolder homepage option in Static Pages is off.
- **Old pages still load**: WCH does not delete objects. Remove pages you no longer need from the bucket yourself.

For other messages, see [Publish errors and troubleshooting](/publish-errors-and-troubleshooting).

## Revoking WCH's access

In RAM, open the `wch-oss-upload` user and disable or delete its AccessKey. WCH can no longer write to the bucket. To remove the destination from WCH as well, open Extensions, then Deployments, and click Delete on the bucket's row.