## 1. Project Overview & Quickstart (kulshekhar/ts-jest)

## File: README.md

<h1 align="center">ts-jest</h1>







It supports all features of TypeScript including type-checking. [Read more about Babel7 + `preset-typescript` **vs** TypeScript (and `ts-jest`)](https://kulshekhar.github.io/ts-jest/docs/babel7-or-ts).

---

| We are not doing semantic versioning and `23.10` is a re-write, run `npm i -D ts-jest@"<23.10.0"` to go back to the previous version |
| ------------------------------------------------------------------------------------------------------------------------------------ |

[ View the online documentation (usage & technical)](https://kulshekhar.github.io/ts-jest)

[ Ask for some help in the `Jest` Discord community](https://discord.gg/j6FKKQQrW9) or [`ts-jest` GitHub Discussion](https://github.com/kulshekhar/ts-jest/discussions)

[ Before reporting any issues, be sure to check the troubleshooting page](TROUBLESHOOTING.md)

[ We're looking for collaborators! Want to help improve `ts-jest`?](https://github.com/kulshekhar/ts-jest/issues/223)

---

## Getting Started

These instructions will get you setup to use `ts-jest` in your project. For more detailed documentation, please check [online documentation](https://kulshekhar.github.io/ts-jest).

|                                      | using npm                      | using yarn                           |
| -----------------------------------: | ------------------------------ | ------------------------------------ |
| **Prerequisites (TypeScript 4.3–6)** | `npm i -D jest typescript`     | `yarn add --dev jest typescript`     |
|                       **Installing** | `npm i -D ts-jest @types/jest` | `yarn add --dev ts-jest @types/jest` |
|                  **Creating config** | `npx ts-jest config:init`      | `yarn ts-jest config:init`           |
|                    **Running tests** | `npm test` or `npx jest`       | `yarn test` or `yarn jest`           |

If your project uses TypeScript 7, follow the [supported side-by-side compiler setup](website/docs/guides/typescript-7.md)
instead of installing `typescript` directly.

## Built With

- [TypeScript](https://www.typescriptlang.org/) - JavaScript that scales
- [Jest](https://jestjs.io/) - Delightful JavaScript Testing
- [`ts-jest`](https://kulshekhar.github.io/ts-jest) - Jest [transformer](https://jestjs.io/docs/next/code-transformation#writing-custom-transformers) for TypeScript _(yes, `ts-jest` uses itself for its tests)_

## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.

## Versioning

We **DO NOT** use [SemVer](https://semver.org/) for versioning. Though you can think about SemVer when reading our version, except our major number follows the one of Jest. For the versions available, see the [tags on this repository](https://github.com/kulshekhar/ts-jest/tags).

## Authors/maintainers

- **Kulshekhar Kabra** - [kulshekhar](https://github.com/kulshekhar)
- **Gustav Wengel** - [GeeWee](https://github.com/GeeWee)
- **Ahn** - [ahnpnl](https://github.com/ahnpnl)
- **Huafu Gandon** - [huafu](https://github.com/huafu)

See also the list of [contributors](https://github.com/kulshekhar/ts-jest/contributors) who participated in this project.

## Supporters

- [JetBrains](https://www.jetbrains.com/?from=ts-jest) has been kind enough to support ts-jest with a [license for open source] (https://www.jetbrains.com/community/opensource/?from=ts-jest).

## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details

---

## File: examples/react-app/README.md

# React + TypeScript + Vite

This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.

Currently, two official plugins are available:

- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh

## Expanding the ESLint configuration

If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:

- Configure the top-level `parserOptions` property like this:

```js
export default {
  // other rules...
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    project: ['./tsconfig.json', './tsconfig.node.json'],
    tsconfigRootDir: __dirname,
  },
}
```

- Replace `plugin:@typescript-eslint/recommended` to `plugin:@typescript-eslint/recommended-type-checked` or `plugin:@typescript-eslint/strict-type-checked`
- Optionally add `plugin:@typescript-eslint/stylistic-type-checked`
- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and add `plugin:react/recommended` & `plugin:react/jsx-runtime` to the `extends` list

---

## File: src/transformers/README.md

# Transformer

See https://dev.doctorevidence.com/how-to-write-a-typescript-transform-plugin-fc5308fdd943

## Boilerplate

```ts
import { SourceFile, TransformationContext, Transformer, Visitor } from 'typescript'

import type { TsCompilerInstance } from 'ts-jest/dist/types'

/**
 * Remember to increase the version whenever transformer's content is changed. This is to inform Jest to not reuse
 * the previous cache which contains old transformer's content
 */
export const version = 1
// Used for constructing cache key
export const name = 'hoist-jest'

export function factory(compilerInstance: TsCompilerInstance) {
  const ts = compilerInstance.configSet.compilerModule
  function createVisitor(ctx: TransformationContext, sf: SourceFile) {
    const visitor: Visitor = (node) => {
      // here we can check each node and potentially return
      // new nodes if we want to leave the node as is, and
      // continue searching through child nodes:
      return ts.visitEachChild(node, visitor, ctx)
    }
    return visitor
  }
  // we return the factory expected in CustomTransformers
  return (ctx: TransformationContext): Transformer => {
    return (sf: SourceFile) => ts.visitNode(sf, createVisitor(ctx, sf))
  }
}
```

---

## File: website/docs/getting-started/options/astTransformers.md

---
title: AST transformers option
---

`ts-jest` by default does hoisting for a few `jest` methods via a TypeScript AST transformer. One can also create custom
TypeScript AST transformers and provide them to `ts-jest` to include into compilation process.

The option is `astTransformers` and it allows ones to specify which 3 types of TypeScript AST transformers to use with `ts-jest`:

- `before` means your transformers get run before TS ones, which means your transformers will get raw TS syntax
  instead of transpiled syntax (e.g `import` instead of `require` or `define` ).
- `after` means your transformers get run after TS ones, which gets transpiled syntax.
- `afterDeclarations` means your transformers get run during `d.ts` generation phase, allowing you to transform output type declarations.

### Examples

#### Basic Transformers

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        astTransformers: {
          before: ['my-custom-transformer'],
        },
      },
    ],
  },
}

export default jestConfig
```

#### Configuring transformers with options

:::important

The `options` config option will be serialized by [`jest-worker`](https://github.com/jestjs/jest/tree/main/packages/jest-worker) therefore only **SERIALIZABLE** values are allowed.

:::

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        astTransformers: {
          before: [
            {
              path: 'my-custom-transformer-that-needs-extra-opts',
              options: {}, // extra options to pass to transformers here
            },
          ],
        },
      },
    ],
  },
}

export default jestConfig
```

### Writing custom TypeScript AST transformers

To write a custom TypeScript AST transformers, one can take a look at [the one](https://github.com/kulshekhar/ts-jest/tree/main/src/transformers) that `ts-jest` is using.

---

## File: website/docs/getting-started/options/babelConfig.md

---
title: Babel Config option
---

`ts-jest` by default does **NOT** use Babel. But you may want to use it, especially if your code rely on Babel plugins to make some transformations. `ts-jest` can call the BabelJest processor once TypeScript has transformed the source into JavaScript.

The option is `babelConfig` and it works pretty much as the `tsconfig` option, except that it is disabled by default. Here is the possible values it can take:

- `false`: the default, disables the use of Babel
- `true`: enables Babel processing. `ts-jest` will try to find a `.babelrc`, `.babelrc.js`, `babel.config.js` file or a `babel` section in the `package.json` file of your project and use it as the config to pass to `babel-jest` processor.
- `{ ... }`: inline [Babel options](https://babeljs.io/docs/en/next/options). You can also set this to an empty object (`{}`) so that the default Babel config file is not used.

### Examples

#### Use default `babelrc` file

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        babelConfig: true,
      },
    ],
  },
}

export default jestConfig
```

#### Path to a `babelrc` file

The path should be relative to the current working directory where you start Jest from. You can also use `\<rootDir>` in the path, or use an absolute path (this last one is strongly not recommended).

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        babelConfig: 'babelrc.test.js',
      },
    ],
  },
}

export default jestConfig
```

or importing directly the config file:

```ts title="jest.config.ts"
import type { Config } from 'jest'
import babelConfig from './babelrc.test.js'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        babelConfig,
      },
    ],
  },
}

export default jestConfig
```

#### Inline compiler options

Refer to the [Babel options](https://babeljs.io/docs/en/next/options) to know what can be used there.

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        babelConfig: {
          comments: false,
          plugins: ['@babel/plugin-transform-for-of'],
        },
      },
    ],
  },
}

export default jestConfig
```

---

## File: website/docs/getting-started/options/compiler.md

---
title: Compiler option
---

The `compiler` option allows you to define the compiler to be used. It'll be used to load the NodeJS module holding the TypeScript compiler.

The default value is `typescript`, which will load the original [TypeScript compiler module](https://www.npmjs.com/package/typescript).
The loaded version will depend on the one installed in your project.

If you use a custom compiler, such as `ttypescript`, make sure its API is the same as the original TypeScript, at least for what `ts-jest` is using.

TypeScript 7.0's native package does not expose this API and cannot be selected here. See the
[TypeScript 7 guide](../../guides/typescript-7.md) for the supported side-by-side setup.

### Example

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        compiler: 'ttypescript',
      },
    ],
  },
}

export default jestConfig
```

---

## File: website/docs/getting-started/options/diagnostics.md

---
title: Diagnostics option
---

The `diagnostics` option configures error reporting.
It can both be enabled/disabled entirely or limited to a specific type of errors and/or files.

If a diagnostic is not filtered out, `ts-jest` will fail the compilation and your test.

### Disabling/enabling

By default all diagnostics are enabled. This is the same as setting the `diagnostics` option to `true`.
To disable all diagnostics, set `diagnostics` to `false`.
This might lead to slightly better performance, especially if you're not using Jest's cache.

### Advanced configuration

The `diagnostics` option's value can also accept an object for more advanced configuration. Each config. key is optional:

- **`warnOnly`**: If specified and `true`, diagnostics will be reported but won't stop compilation (default: _disabled_).
- **`ignoreCodes`**: List of TypeScript error codes to ignore. Complete list can be found [there](https://github.com/Microsoft/TypeScript/blob/main/src/compiler/diagnosticMessages.json). By default here are the ones ignored:
  - `6059`: _'rootDir' is expected to contain all source files._
  - `18002`: _The 'files' list in config file is empty._ (it is strongly recommended including this one)
  - `18003`: _No inputs were found in config file._
- **`exclude`**: If specified, diagnostics of source files which path **matches** will be ignored. This works a bit
  similar to `tsconfig` option [exclude](https://www.typescriptlang.org/tsconfig#exclude) with the only difference is that
  in TypeScript, `exclude` will also exclude files from compilation process.
- **`pretty`**: Enables/disables colorful and pretty output of errors (default: _enabled_).

### Examples

#### Disabling diagnostics

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        diagnostics: false,
      },
    ],
  },
}

export default jestConfig
```

#### Advanced options

##### Enabling diagnostics for test files only

Assuming all your test files ends with `.spec.ts` or `.test.ts`, using the following config will enable error reporting only for those files:

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        diagnostics: {
          exclude: ['!**/*.(spec|test).ts'],
        },
      },
    ],
  },
}

export default jestConfig
```

##### Do not fail on first error

While some diagnostics are stop-blockers for the compilation, most of them are not. If you want the compilation (and so your tests) to continue when encountering those, set the `warnOnly` to `true`:

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        diagnostics: {
          warnOnly: true,
        },
      },
    ],
  },
}

export default jestConfig
```

##### Ignoring some error codes

All TypeScript error codes can be found [there](https://github.com/Microsoft/TypeScript/blob/main/src/compiler/diagnosticMessages.json). The `ignoreCodes` option accepts this values:

1. A single `number` (example: `1009`): unique error code to ignore
2. A `string` with a code (example `"1009"`, `"TS1009"` or `"TS1009"`)
3. A `string` with a list of the above (example: `"1009, TS2571, 4072"`)
4. An `array` of one or more from `1` or `3` (example: `[1009, "TS2571", "6031"]`)

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        diagnostics: {
          ignoreCodes: [2571, 6031, 18003],
        },
      },
    ],
  },
}

export default jestConfig
```

---

## File: website/docs/getting-started/options/isolatedModules.md

---
title: isolatedModules option
---

:::warning DEPRECATED

This page is now **DEPRECATED** and will be removed together with the config option `isolatedModules` in the next major release. Please use `isolatedModules` option in `tsconfig.json` instead.

:::

By default `ts-jest` uses TypeScript compiler in the context of a project (yours), with full type-checking and features.
But it can also be used to compile each file separately, what TypeScript calls an 'isolated module'.
That's what the `isolatedModules` option (which defaults to `false`) does.

You'll lose type-checking ability and some features such as `const enum`, but in the case you plan on using Jest with the cache disabled (`jest --no-cache`), your tests will then run much faster.

Here is how to disable type-checking and compile each file as an isolated module:

### Example

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process js/ts with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process js/ts/mjs/mts with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        isolatedModules: true,
      },
    ],
  },
}

export default jestConfig
```

## Performance

Using `isolatedModules: false` comes with a cost of performance comparing to `isolatedModules: true`. There is a way
to improve the performance when using this mode by changing the value of `include` in `tsconfig` which is used by `ts-jest`.
The least amount of files which are provided in `include`, the more performance the test run can gain.

### Example

```json title="tsconfig.json"
{
  // ...other configs
  "include": ["my-typings/*", "my-global-modules/*"]
}
```

## Caveats

Limiting the amount of files loaded via `include` can greatly boost performance when running tests. However, the trade off
is `ts-jest` might not recognize all files which are intended to use with `jest`. One can run into issues with custom typings,
global modules, etc...

The suggested solution is what is needed for the test environment should be captured by
glob patterns in `include`, to gain both performance boost and avoid breaking behaviors.

---

## File: website/docs/getting-started/options/stringifyContentPathRegex.md

---
title: Stringify content option
---

The `stringifyContentPathRegex` option has been kept for backward compatibility of `__HTML_TRANSFORM__`
It's a regular expression pattern used to match the path of file to be transformed.
If it matches, the file will be exported as a module exporting its content.

Let's say for example that you have a file `foo.ts` which contains `export default "bar"`, and your `stringifyContentPathRegex` is set to `foo\\.ts$`, the resulting module won't be the result of compiling `foo.ts` source, but instead it'll be a module which exports the string `"export default \"bar\""`.

**CAUTION**: Whatever file(s) you want to match with `stringifyContentPathRegex` pattern, you must ensure the Jest `transform` option pointing to `ts-jest` matches them. You may also have to add the extension(s) of this/those file(s) to `moduleFileExtensions` Jest option.

### Example

In the `jest.config.js` version, you could do as in the `package.json` version of the config, but extending from the preset will ensure more compatibility without any changes when updating.

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  moduleFileExtensions: ['html'],
  transform: {
    // [...]
    '\\.html$': [
      'ts-jest',
      {
        stringifyContentPathRegex: /\.html$/,
      },
    ],
  },
}

export default jestConfig
```

---

## File: website/docs/getting-started/options/tsconfig.md

---
title: TypeScript Config option
---

The `tsconfig` option allows you to define which `tsconfig` JSON file to use. An inline [compiler options][] object can also be specified instead of a file path.

By default `ts-jest` will try to find a `tsconfig.json` in your project. If it cannot find one, it will use the default TypeScript [compiler options][]; except, `ES2015` is used as `target` instead of `ES5`.

If you need to use defaults and force `ts-jest` to use the defaults even if there is a `tsconfig.json` in your project, you can set this option to `false`.

### Examples

#### Path to a `tsconfig` file

The path should be relative to the current working directory where you start Jest from. You can also use `<rootDir>` in the path to start from the project root dir.

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: JestConfigWithTsJest = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        tsconfig: 'tsconfig.test.json',
      },
    ],
  },
}

export default jestConfig
```

#### Inline compiler options

Refer to the TypeScript [compiler options][] for reference.
It's basically the same object you'd put in your `tsconfig.json`'s `compilerOptions`.

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        tsconfig: {
          importHelpers: true,
        },
      },
    ],
  },
}

export default jestConfig
```

#### Disable auto-lookup

By default `ts-jest` will try to find a `tsconfig.json` in your project. But you may not want to use it at all and keep TypeScript default options. You can achieve this by setting `tsconfig` to `false`.

```ts title="jest.config.ts"
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        tsconfig: false,
      },
    ],
  },
}

export default jestConfig
```

[compiler options]: https://www.typescriptlang.org/tsconfig

## 2. Official Technical Reference & Guides (kulshekhar/docs)

## File: README.md

Linode Guides and Tutorials
====================

This repository contains all the tutorials featured at [linode.com/docs](https://linode.com/docs). Please feel free to contribute by suggesting document improvements, identifying corrections, or submitting updates.

If you'd like to write for us, please apply via our [contributing page](https://linode.com/docs/contribute). Then, see the [Linode Writer's Formatting Guide](https://www.linode.com/docs/linode-writers-formatting-guide) for more information regarding content and formatting.

---

## File: docs/index.md

---
title: Guides & Tutorials
layout: front_page_layout
tiles:
  - { title: 'Getting Started', description: 'Get to Hello World on Linode', url: 'getting-started', icon: 'book' }
  - { title: 'Quick Answers', description: 'How to get up and running quickly', url: 'quick-answers', icon: 'bolt' }
  - { title: 'Linode Platform', description: 'Accounts, Features, Billing, Support & more', url: 'platform', icon: 'cube' }
  - { title: 'Websites', description: 'Start hosting services on your Linode', url: 'websites', icon: 'laptop' }
  - { title: 'Web Servers', description: 'LAMP, Apache, Nginx, & more', url: 'web-servers', icon: 'globe' }
  - { title: 'IPs, Networking & Domains', description: 'Connect to your Linode', url: 'networking', icon: 'sitemap' }
  - { title: 'Security, Upgrades & Backups', description: 'Keep your data safe', url: 'security', icon: 'lock' }
  - { title: 'Email', description: 'Email servers and clients', url: 'email', icon: 'envelope' }
  - { title: 'Databases', description: 'MySQL, PostgreSQL, Redis, Oracle & more', url: 'databases', icon: 'database' }
  - { title: 'Uptime & Analytics', description: 'Load balancing & monitoring', url: 'uptime', icon: 'bar-chart-o' }
  - { title: 'Applications', description: 'Web applications on Linode', url: 'applications', icon: 'cogs' }
  - { title: 'Game Servers', description: 'Host a multiplayer game server on Linode', url: 'game-servers', icon: 'gamepad' }
  - { title: 'Development', description: 'Create development environments on Linode', url: 'development', icon: 'code' }
  - { title: 'Troubleshooting', description: 'Diagnose & resolve problems', url: 'troubleshooting', icon: 'question-circle' }
  - { title: 'Tools & Reference', description: 'Useful tools for experts & beginners', url: 'tools-reference', icon: 'wrench' }
---

---

## File: docs/getting-started.md

---
author:
  name: Linode
  email: docs@linode.com
keywords: 'linode guide,getting started,linode quickstart,quick start,boot,configuration profile,update,hostname,timezone,SSH'
license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)'
modified: Friday, March 3rd, 2017
modified_by:
  name: Linode
published: 'Sunday, July 19th, 2009'
title: Getting Started with Linode
---

Congratulations on selecting Linode as your cloud hosting provider! This guide will help you sign up for an account, deploy a Linux distribution, boot your Linode, and perform some basic system administration tasks.

<script src="//fast.wistia.net/assets/external/E-v1.js" async></script>

## Sign Up

If you haven't already signed up for a Linode account, start here.

1.  Create a new account at the [Sign Up page](https://manager.linode.com/signup).
2.  Sign in and enter your billing and account information. Most accounts are activated instantly but some require manual review prior to activation. If your account is not immediately activated, you will receive an email with additional instructions.
3.  Select a Linode plan and data center location

    

If you're unsure of which data center to select, see our [speed test](http://www.linode.com/speedtest) to determine which location provides the best performance for your target audience. You can also generate [MTR reports](/docs/networking/diagnostics/diagnosing-network-issues-with-mtr/) for each of the data centers to determine which of our facilities provides the best latency from your particular location.

## Provisioning Your Linode

After your Linode is created, you'll need to prepare it for operation by deploying a Linux distribution.

### Logging in to the Linode Manager

The [Linode Manager](https://manager.linode.com) is a web-based control panel that allows you to manage your Linode virtual servers and services. Log in with the `username` and `password` you created when you signed up. After you've created your first Linode, you can use the Linode Manager to:

* Boot and shut down your virtual server,
* Access monitoring statistics,
* Update your billing and account information,
* Request support and perform other administrative tasks.

### Deploying an Image

After creating a new Linode, select it to open the Linode Manager Dashboard.

1.  Click on **Deploy an Image**.

    [](/docs/assets/linode-manager-dashboard-newacct.png)

    The *Deploy* page opens.

    [](/docs/assets/linode-manager-deploy-an-image.png)

2.  Select a Linux distribution from the **Image** menu. You can choose from [Arch Linux](http://www.archlinux.org/), [CentOS](http://www.centos.org/), [Debian](http://www.debian.org/), [Fedora](http://fedoraproject.org/), [Gentoo](http://www.gentoo.org/), [openSUSE](http://www.opensuse.org/), [Slackware](http://www.slackware.com/), and [Ubuntu](http://www.ubuntu.com/) to install on your Linode. If you're new to the Linux operating system, consider selecting Ubuntu 16.04 LTS. Ubuntu is the most popular distribution among Linode customers and one of the most well supported by online communities, so resolving any issues you may have should be simple.

3.  Enter a size for the disk in the **Deployment Disk Size** field. By default all of the available space is allocated, but you can set a lower size if you plan on cloning a disk or creating multiple configuration profiles. You can always create, resize, and delete disks later.

4.  Select a swap disk size from the **Swap Disk** menu.

5. Enter a root password for your Linode in the **Root Password** field. This password must be provided when you log in to your Linode via SSH and must be at least 6 characters long and contain characters from two of the following categories:

    -   lowercase and uppercase case letters
    -   numbers
    -   punctuation characters

6.  Click **Deploy**.

    You can use the Linode Manager's Dashboard to monitor the progress in real time as shown below.

    [](/docs/assets/linode-manager-provisioning-status.png)

    When the deployment process is completed, your Linode's configuration profile will appear on the Dashboard.

    [](/docs/assets/linode-manager-configuration-profile.png)

    {: .note }
    >
    > Use a [StackScript](http://www.linode.com/stackscripts) to quickly deploy a customized Linux distribution. Some of the most popular StackScripts do things like install the Apache web server, configure a firewall, and set up the WordPress content management system. They're easy to use. Just find a StackScript, complete the form, and deploy.

## Booting Your Linode

Your Linode is now provisioned with the distro of your choice but it's turned off, as indicated in the Dashboard.

Click **Boot** to turn on your Linode.

[](/docs/assets/linode-manager-power-on-linode.png)

When booted, the **Server Status** will change from **Powered Off** to **Running** and there will be a successfully completed **System Boot** job in the **Host Job Queue**.

[](/docs/assets/linode-manager-linode-booted.png)

## Connecting to Your Linode via SSH

Communicating with your Linode is usually done using the secure shell (SSH) protocol. SSH encrypts all of the data transferred between the SSH client application on your computer and the Linode, including passwords and other sensitive information. There are SSH clients available for every operating system.

### SSH Overview

-   **Linux:** You can use a terminal window, regardless of desktop environment or window manager.
-   **Mac:** The *Terminal* application comes pre-installed with OS X and you can launch it from *Finder* > *Applications* > *Utilities*. You could also use the free [iTerm 2 application](http://www.iterm2.com/). For a walkthrough of connecting to your Linode for the first time **with OS X** (which also directly applies to Linux), see the following video:

    

-   **Windows:** There is no native SSH client but you can use a free, open source application called [PuTTY](/docs/networking/using-putty). For a walkthrough of connecting to your Linode in Windows using PuTTY, see the following video:

    

    {: .note }
    >
    > These videos were created by [Treehouse](http://www.teamtreehouse.com), which is offering Linode customers a free one month trial. [Click here](http://teamtreehouse.com/join/free-month?utm_source=linode&utm_medium=partnership&utm_campaign=linode-2013&cid=1124) to start your free trial and start learning web design, web development, and more.

### Find the IP Address of Your Linode

Your Linode has a unique *IP address* that identifies it to other devices and users on the Internet. For the time being, you'll use the IP address to connect to your server. After you perform some of these initial configuration steps outlined in the Linode Quick Start Guides, you can use [DNS records](/docs/hosting-website#sph_adding-dns-records) to point a domain name at your server and give it a more recognizable and memorable identifier.

Find your Linode's IP address from the [Linode Manager](https://manager.linode.com).

1.  Click the **Linodes** tab.
2.  Select your Linode.
3.  Click the **Remote Access** tab.
4.  Copy the addresses in the Public IPs section.

    [](/docs/assets/1710-remote_access_ips.png)

In this example, the Linode's IPv4 address is *96.126.109.54* and its IPv6 address is *2600:3c03::f03c:91ff:fe70:cabd*. Unless your Internet service provider supports IPv6, you'll want to the use the IPv4 address.

### Logging in for the First Time

Once you have the IP address and an SSH client, you can log in via SSH. The following instructions are written for Linux and Mac OS X. If you're using PuTTY as your SSH client in Windows, follow [these instructions](/docs/networking/using-putty).

1.  Enter the following into your terminal window or application. Replace the example IP address with your Linode's IP address:

        ssh root@123.456.78.90

2.  If this is the first time connecting to your Linode, you'll see the authenticity warning below. This is because your SSH client has never encountered the server's key fingerprint before. Type `yes` and press **Enter** to continue connecting.

        The authenticity of host '123.456.78.90 (123.456.78.90)' can't be established.
        RSA key fingerprint is 11:eb:57:f3:a5:c3:e0:77:47:c4:15:3a:3c:df:6c:d2.
        Are you sure you want to continue connecting (yes/no)?

    After you enter `yes`, the client confirms the addition:

        Warning: Permanently added '123.456.78.90' (RSA) to the list of known hosts.

3.  The login prompt appears for you to enter the password you created for the `root` user above.

        root@123.456.78.90's password:

4.  The SSH client initiates the connection. You'll know you're logged in when the following prompt appears:

        root@li123-456:~#

 {: .note }
>
> If you recently rebuilt an existing Linode, you might receive an error message when you try to
> reconnect via SSH. SSH clients try to match the remote host with the known keys on your desktop computer, so when you rebuild your Linode, the remote host key changes.
>
>To reconnect via SSH, revoke the key for that IP address.
>
>For Linux and Mac OS X:
>
> ~~~
> ssh-keygen -R 123.456.789
> ~~~
>
> For Windows, PuTTY users must remove the old host IP addresses manually. PuTTY's known hosts are in the registry entry:
>
>     HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\SshHostKeys

## Installing Software Updates

The first thing you should do when connecting to your Linode is update the Linux distribution's software. This applies the latest security patches and bug fixes to help protect your Linode against unauthorized access.

Installing software updates should be performed *regularly*. If you need help remembering, try creating a monthly alert with the calendar application on your desktop computer.

### Ubuntu / Debian

    apt-get update && apt-get upgrade

{: .note }
>
>Ubuntu may prompt you when the Grub package is updated.
>If prompted, select `keep the local version currently installed`.

### CentOS

    yum update

### Fedora

    dnf upgrade

### Arch Linux

    pacman -Syu

### Gentoo

    emaint sync

{: .note}
>emaint is a [plugin](https://gentoo.org/support/news-items/2015-02-04-portage-sync-changes.html) for emerge, so `emerge --sync` is no longer used and that command now just calls `emaint sync`. The sync command uses the `auto` option by default. See [here](https://wiki.gentoo.org/wiki/Project:Portage/Sync#Operation) for more info on what that means and when you may want to change it. For more information on how to use `emaint`, refer to its [man page](https://dev.gentoo.org/~zmedico/portage/doc/man/emaint.1.html).

After running a sync, it may end with a message that you should upgrade Portage using a *--oneshot* emerge comand. If so, run the Portage update. Then update the rest of the system:
    
    emerge --uDN @world

### Slackware

    slackpkg update
    slackpkg upgrade-all

See the [Slackpkg documentation](http://slackpkg.org/documentation.html) for more information on package management in Slackware.

## Setting the Hostname

You'll need to set your system's hostname and fully qualified domain name (FQDN). Your hostname should be something unique. Some people name their servers after planets, philosophers, or animals. Note that the system's hostname has no relationship to websites or email services hosted on it, aside from providing a name for the system itself. Your hostname should *not* be "www" or anything too generic.

Once you're done, you can verify by running the command `hostname`.

{: .note }
>
> If you're unfamiliar with Linux, one of the first things you'll need to learn is how to use [nano](/docs/linux-tools/text-editors/nano), a text editor included with most distributions. To open a file for editing, type `nano file.txt` where "file.txt" is the name of the file you want to create or edit. If the file is not in your current working directory, specify the entire file path. For example, open the `hosts` file with:
>
>     nano /etc/hosts
>
>When you're finished editing, press `Control-X`, then `Y` to save the changes and `Enter` to confirm.

For a walkthrough of setting system's hostname and timezone, see the following video:



{: .note }
>
> This video was created by [Treehouse](http://www.teamtreehouse.com), which is offering Linode customers a free one month trial. [Click here](http://teamtreehouse.com/join/free-month?utm_source=linode&utm_medium=partnership&utm_campaign=linode-2013&cid=1124) to start your free trial and start learning web design, web development, and more.

### Arch / CentOS 7 / Debian 8 / Fedora version 18 and above / Ubuntu 15.04 and above

Replace `hostname` with one of your choice.

    hostnamectl set-hostname hostname

### Debian 7 / Slackware / Ubuntu 14.04

Replace `example_hostname` with one of your choice.

    echo "example_hostname" > /etc/hostname
    hostname -F /etc/hostname

Check if the file `/etc/default/dhcpcd` exists, and it's contents.

    cat /etc/default/dhcpcd | grep SET_HOSTNAME

If the returned value is `SET_HOSTNAME='yes'`, edit `/etc/default/dhcpcd` and comment out the `SET_HOSTNAME` directive:

{: .file-excerpt }
/etc/default/dhcpcd
: ~~~
  #SET_HOSTNAME='yes'
  ~~~

### CentOS 6 / Fedora version 17 and below

Replace `hostname` with one of your choice.

    echo "HOSTNAME=hostname" >> /etc/sysconfig/network
    hostname "hostname"

### Gentoo

Enter the following commands to set the hostname, replacing `hostname` with the hostname of your choice:

    echo "HOSTNAME=\"hostname\"" > /etc/conf.d/hostname
    /etc/init.d/hostname restart

### Update /etc/hosts

Update the `/etc/hosts` file. This file creates static associations between IP addresses and hostnames, with higher priority than DNS.

1.  Every `hosts` file should begin with the line `127.0.0.1 localhost.localdomain localhost`, although the naming may be slightly different between Linux distributions. `127.0.0.1` is the [**loopback address**](https://en.wikipedia.org/wiki/Loopback#Virtual_loopback_interface), and is used to send IP traffic internally on the system. You can leave this line alone.

    Some distributions may also ship with a line for `127.0.1.1` in their `hosts file`. This is the loopback domain, and can be ignored in most cases.

2.  Add a line for your Linode's public IP address. You can associate this address with your Linode's **Fully Qualified Domain Name** (FQDN) if you have one, and with the local hostname you set in the steps above. In the example below, `203.0.113.10` is our public IP address, `hostname` is our local hostname, and `hostname.example.com` is our FQDN.

As with the hostname, the domain name part of your FQDN does not necessarily need to have any relationship to websites or other services hosted on the server (although it may if you wish). As an example, you might host "www.something.com" on your server, but the system's FQDN might be "mars.somethingelse.com."

{:.file }
/etc/hosts
: ~~~
  127.0.0.1 localhost.localdomain localhost
  203.0.113.10 hostname.example.com hostname
  ~~~

If you have IPv6 enabled on your Linode, you may also want to add an entry for your IPv6 address, as shown in this example:

{:.file }
/etc/hosts
: ~~~
  127.0.0.1 localhost.localdomain localhost
  203.0.113.10 hostname.example.com hostname
  2600:3c01::a123:b456:c789:d012 hostname.example.com hostname
  ~~~

The value you assign as your system's FQDN should have an "A" record in DNS pointing to your Linode's IPv4 address. For Linodes with IPv6 enabled, you should also set up a "AAAA" record in DNS pointing to your Linode's IPv6 address. For more information on configuring DNS, see [Adding DNS Records](/docs/hosting-website#sph_adding-dns-records).

## Setting the Timezone

By default, a Linode's Linux image will be set to UTC time (also known as Greenwich Mean Time) but this can be changed. It may be better to use the same timezone which a majority of your users are located in, or that you live in to make log file timestamps more sensible.

### Debian / Ubuntu

    dpkg-reconfigure tzdata

### Arch Linux and CentOS 7

View the list of available time zones.

    timedatectl list-timezones

Use the `Up`, `Down`, `Page Up` and `Page Down` keys to navigate. Find the time zone which you want. Remember it, write it down or copy it as a mouse selection. Then press **q** to exit the list.

To set the time zone:

    timedatectl set-timezone 'America/New_York'

### Gentoo

View the list of available time zones.

    ls /usr/share/zoneinfo

Write the selected time zone to the `/etc/timezone` file.

*Example (for Eastern Standard Time)*:

    echo "EST" > /etc/timezone

Configure the `sys-libs/timezone-data` package, which will set `/etc/localtime` appropriately.

    emerge --config sys-libs/timezone-data

### All Other Distributions

Manually symlink a zone file in `/usr/share/zoneinfo` to `/etc/localtime`.

1.  View the list of available zone files.

        ls /usr/share/zoneinfo

2.  Then create the link using the zone file you want.

    *Example*:

        ln -sf /usr/share/zoneinfo/EST /etc/localtime ## for Eastern Standard Time

### Checking the Time

View the current date and time according to your server.

    date

The output should look similar to: `Thu Feb 16 12:17:52 EST 2012`.

## Next Steps

Now that you have an up-to-date Linode, you'll need to secure your Linode and protect it from unauthorized access. Read the [Securing Your Server](/docs/security/securing-your-server) quick start guide to get going.